Codify All Documentation / Manuals

[blynch-newpi]

For some reason I can't get 2 directories to come up. Under documentation where there is the "IT" directory, I also have developer and end-user, mimicking your structure on your site. For whatever reason they won't come up, but I wanted to mention it as it appears to just have an IT folder. After looking at your issue comments though Andy, do we maybe not want to break up documentation based on roles? Or is that a good way to go? I'm trying to put myself in the shoes of a wide range of readers and how they might approach searching for documents.

[gohanman]

What does it show if you type "git status" in the documentation directory? To me, this sounds like untracked files that need to be added to the project (i.e., "git add developer end-user").

Roles strike me as an excellent middle ground, especially for end-user documentation, to provide organization without getting too lost in store-specific semantics - e.g., Merchandising instead of Scanning or Buyers. I do think developer documentation should be clearly separated. In my mind, end-user (with roles) should encompass all day to day operations. Developer should essentially explain adding features - what modularity is available, how to extend cleanly, etc.

[blynch-newpi]

git status in that directory didn't show anything helpful. It just kept saying there was nothing to commit. So I created some test .txt files in each directory and that seemed to flag them so I pushed them up.

[blynch-newpi]

I have an IS4C-specific mediawiki install using mysql locally, in-house to New Pi. I am going to start translating Andy's docs and organizing in this wiki. Chris Von R. is open to using NCGA domain resources like, techhub.coop or some other such resource for this. Until he can get time and such do something like that, I will build and backup in-house to New Pi. Maybe for status checks I will send the group screenshots or something.

[blynch-newpi]

Install something like: http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi

For readability of any source code in IS4C documentation. It's possible mediawiki's default install has markup to handle this but haven't found it yet.

[blynch-newpi]

From here on out, can someone think of a way to mark all of the documentation as new? Basically, I'm organizing sections and copying and pasting into the wiki now and I don't want a developer to make a change to the existing files and have me miss it. Should we just create a bucket for you to put it in and that will be my 'queue' of docs to get to?

[gohanman]

The commit history sort of shows this. Would it work to just put DOCUMENTATION or something in the first line of the commit comment so you can just scan down the list instead of clicking into each one to see which files changed?

(Also, put up some batch info before reading this, so my most recent commit fails to follow my own suggestion. Oops.)

[blynch-newpi]

No problem. Yes, I like the documentation suggestion. Let's all agree to that until we find it doesn't work for us. [edit: I am up to date on your 3 new batch docs into the wiki] From here on out, everybody put DOCUMENTATION when making a documentation commit. Thank you.

[blynch-newpi]

This mediawiki extension: http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi has now been installed on the local IS4CDoc wiki at New Pi. PHP code now looks great and legible with the provided markup. There is support other languages and I will markup those as needed.

[blynch-newpi]

Documentation up to date (meaning pasted into wiki, not edited/finalized) as of 2011-05-02

[blynch-newpi]

Documentation up to date as of 2011-07-14. Thanks for noting the DOCUMENTATION tag in your tags Andy and especially doing it when you're only making a change. A HUGE help to me. Thanks!

[blynch-newpi]

Wiki up to date as of last doc commit of 2011-07-25.