On 26/03/15 10:52, Ashley Sheridan wrote:
I know this isn't strictly PHP, but I thought the collective knowledge here is better than what I'll get on stack overflow!
Basically, I have a project I'm working on in my spare time, and so far have been documenting the whole thing in one large readme on github. A print preview puts it at ~16 pages.
The project has a lot of scope for growth, so documentation will only increase.
My question is, when does it become worth breaking one large document into several smaller chunks? What are your own views on this? Has anyone had a similar issue in the past?
I remember a technique I used some years ago called "literate programming".
It's a technique where you put code ànd documentation in 1 large text file.
On the "edge" between a code chunk and a documentation chunk, you put
some qualifier.
Before compilation, a pre-processing tool cuts up the text file,
collates all code chunks.
A documentation pre-processor on the other hand would apply different
formatting on doc and code chunks, improving readability.
This allows, for example, to use HTML or LaTeX mark-up in your
documentation, and an indented, courer-style format for the code
At he time, I used a tool called noweb , but literate programming should
give you some hints.
Regards, Bert
--
PHP General Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
