Hacker News Reader

Comment by dman | Hacker News Reader

That is a good point. Reason I was asking this question is because of my current workflow. The workflow looks has the following stages -

Stage 1. Read a bunch of papers and blogs for the problem being solved.

Stage 2. Assimilate relevant ideas and come up with some kind of design. This stage usually involves hand written notes, doodles etc.

Stage 3. Write code based on the design.

I currently document stages 1 and 2 in a wiki but since it lives far away from the code, those things dont get used as much as I would like. Being able to add written reference material in a file along with the code and then having the ability to see a code only view seems appealing from where I am at currently.

View on HN

Since you are doing stage 1 and 2 on a computer system, you could go on, and write the code of stage 3 in that very same wiki too!

Then write a spider to scan this wiki, extract the code blocks, and assemble a compilable program, and you're done, wiki literate programming!

A wiki is a terrible instrument for writing software documentation. For example, there is no revision control to track changes as required by by changes in the code, there is much duplication. I could go on, and on, why a wiki is not optimal for any documentation associated to a software project.

Better to use a system like DITA or dockbook.

Which wiki engine do you have in mind? There certainly is revision control in MediaWiki, Confluence, and others. Granted, I wouldn't use those in place of a source code revision control system such as git. There are generally no "annotate"/"blame" or "pickaxe" features. I would agree with writing something code-friendly in the first place, examples of which would include DocBook and Restructured Text.

There's at least one wiki that's built on top of Git:

https://github.com/gollum/gollum

There's also Gitit, which supports multiple VCSs including git:

https://github.com/jgm/gitit

Maybe to get the wiki closer to the code, you could put links to relevant wiki pages in your code comments. Some editors even recognize URLs in the code and allow you to click on them for instant access. And if your code repository is HTTP-accessible, you could put links to your code on your wiki pages.

Reply on news.ycombinator.com