Re: Documentation best practices

On 26 Mar 2015 at 09:52, Ashley Sheridan <ash@ashleysheridan.co.uk> 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? My internal doc for my project is now 36 pages long and has always been a Pages [1] document with ToC, images, chapters, sections, and diagrams. If anyone were to ask me for it I'd send it them as a pdf. I'd say your doc is already large enough to need structuring. Forcing yourself to do that, I find, also assists with the project itself, because if you've implemented something in a slightly clumsy way, you may go back and redo it just to make the doc easier to write :-) [1] which unlike Word doesn't sometimes hide images in the cracks between pages. -- Cheers -- Tim