Re: [docs] How do I use Github?

new topic     » goto parent     » topic index » view thread      » older message » newer message
irv said...

Forking is crazy - there is 100% chance that someone will introduce at least one error into the source, so there will need to be intensive testing before the release.

The need for testing is true no matter who is committing updated source. But I see your point. That's why having a few devs working off other people's submissions is probably the best way (for now).

irv said...

Tickets are the only way as long as the misguided idea of trying to produce accurate and useful docs from markup in the source remains the rule.

Please bear with us as we transition to a new method. This is the old way, adopted probably because it's standard practice in a lot of projects. We can transition to a new model, but for now we're having to use the old way. I think Greg is the only dev working on a release, so anything you can do to help and not hinder the work is appreciated.

irv said...

Look at the source and see how you have to wade thru the "documentation" to find the actual working code.

I have, and it was very easy to manage. As long as the tickets are comprehensive in the request, fixing the docs should be relatively straightforward and easy (but maybe not quick, since only a couple of people with day jobs are working on them).

irv said...

It's unhelpful, it's so limited that it can never produce modern, attractive and informative documentation, and I don't want to bother supporting the idea any further.

And that's fine. You don't have to. It's just that your help will make the transition quicker and easier. We're all having to suffer at the moment, and if we want an up-to-date, modern Euphoria, this is just the way it's going to be for now.

irv said...

I wonder who made up this rule that "here docs" were the only acceptable option and no others should be considered?

While this is irrelevant, I think it is a common practice. According to this Wikipedia article, "Software documentation,"

Technical documentation embedded in source code
Often, tools such as Doxygen, NDoc, Visual Expert, Javadoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText, or Universal Report can be used to auto-generate the code documents—that is, they extract the comments and software contracts, where available, from the source code and create reference manuals in such forms as text or HTML files.

The idea of auto-generating documentation is attractive to programmers for various reasons. For example, because it is extracted from the source code itself (for example, through comments), the programmer can write it while referring to the code, and use the same tools used to create the source code to make the documentation. This makes it much easier to keep the documentation up-to-date.

Of course, a downside is that only programmers can edit this kind of documentation, and it depends on them to refresh the output (for example, by running a cron job to update the documents nightly). Some would characterize this as a pro rather than a con. }}}

new topic     » goto parent     » topic index » view thread      » older message » newer message


Quick Links

User menu

Not signed in.

Misc Menu