4 ms·

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

by dman 11y ago

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.

informatimago 11y ago
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!
- skia 11y ago
  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.
  - minopret 11y ago
    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.
    - greenyoda 11y ago
      There's at least one wiki that's built on top of Git: https://github.com/gollum/gollum https://github.com/gollum/gollum
      - mrob 11y ago
        There's also Gitit, which supports multiple VCSs including git: https://github.com/jgm/gitit https://github.com/jgm/gitit
greenyoda 11y ago
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.

by dman 11y ago

informatimago 11y ago

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!

skia 11y ago
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.
- minopret 11y ago
  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.
  - greenyoda 11y ago
    There's at least one wiki that's built on top of Git: https://github.com/gollum/gollum https://github.com/gollum/gollum
    - mrob 11y ago
      There's also Gitit, which supports multiple VCSs including git: https://github.com/jgm/gitit https://github.com/jgm/gitit

greenyoda 11y ago

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.