Re: [docs] How do I use Github?

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

The question remains. What is the workflow?

Two methods:

Fork Euphoria

Or

write tickets

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. Plus there will be multiple versions of the docs, so someone has to decide which version is the most appropriate and accurate, then merge them all.

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. It can't work, and if I had tried that in my former job, I'd have been fired.

Look at the source and see how you have to wade thru the "documentation" to find the actual working code. 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.

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

Rant follows.


Forking is crazy.

Tickets is crazy

Here docs is crazy.


Test case is "datetime.e"

Datetime issues

UTC has replace GTM

The interval "Date" makes no sense for add) and subtract) sub-programs.

Many examples, still, do not satisfy basic cut-paste-run.

The clarity of explanations could be improved.

I want hashtags for every topic to make writing documentation easier, to make searching easier, and to make indexing documentation easier.

Multiple authors will never create uniform formatting--one person will ultimately have to go over all of the docs.

Documentation has to be re-written continuously, not written.

Fork

I have a fork on my computer that I can not merge into my Github repository fork of the true Euphoria; which I turn I cannot merge into the true Euphoria source. Irv can not comment or edit my fork.

I am getting the impression that Github is not intended to work nicely with Linux. Using the Windows operating system is too difficult for me (I think Windows is getting to a billion installs; that's a billion people smarter than me.)

Tickets

There are a bunch of tickets marked "fixed" which I do not consider to be fixed. Do I enter a ticket to report these tickets? Even if I wanted to, there is no mechanism for me to fix a ticket.

Here Docs

Greatest fear in writing docs is harming the actual source-code. Editing docs in source-code is not pleasant because you have to navigate past all of the source-code to get to the documentation. Editing " - - " lines of source-code slows down the process of writing documentation. Source-code is going to get bloated with documentation and examples. I can not edit the source-code to create documentation because I do not (yet) get along with Github. Github does not like Linux?--I am too feeble to figure out if this is true.

Wiki/Pastey

No way coerce them to work for editing docs. Maybe in the future Greg will invent something.

As Mark Twain, and others, have stated "I would have written a shorter reply if I had the time."

_tom

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

Search



Quick Links

User menu

Not signed in.

Misc Menu