41–50 of 55 posts
I assume that's because they may be documenting upcoming features before they are announced.
1. https://cloud.githubusercontent.com/assets/64050/5449088/7ad...
Unfortunately the repository (as suggested by the screenshot[1]) seems to be private: https://github.com/github/help-docs I assume that's because they may be documenting upcoming features before they are announced. 1. https://cloud.githubusercontent.com/assets/64050/5449088/7ad...
Earlier quoted context omitted.
Awe, negative points? Really? You know you were thinking it when you saw the link title.
If everyone was already thinking it, what makes you think they want to see it in the comments?
You know, sometimes it's ok to find humor in things.
This title alone is gitception!
I personally found this write up extremely interesting and exciting. I have always been interested in documentation and its order in the priority list of tasks which a development team has to tackle. It is not an original observation that documentation is critically important to the success of a project/code-base and yet it is often the last artifact produced (and many skip it altogether). I have recently been extrem…
I wish people would stop viewing documentation as an additional formal step needed to 'package' the software (a nasty chore) and instead viewed it as an exercise in communicating as clearly and concisely as possible what the project is about and how it works.
The number one thing on my wishlist for any project's documentation is simply a glossary, which is trivial to create but is almost never done. Virtually every project has special terms for artefacts, usage, features, etc. which are burned into developers' skulls so deeply that they often forget that outsiders do not use this special terminology.
It gets worse when multiple terms refer to the same thing and the same terms refer to multiple (often ever so slightly different) things.
No fancy technology needed to write one of these things either. A simple text file will do.
The other thing that bugs me is how much documentation is simply describing code that should exist but doesn't. Scripts to build a project or deploy it, for instance. Or mindless test scripts.
Earlier quoted context omitted.
If everyone was already thinking it, what makes you think they want to see it in the comments?
Well, given that I imagine only mods can set negative value to a post, I'm going to infer that the mods didn't like seeing it in the comments. You know, sometimes it's ok to find humor in things.
Github's convention that web pages for a project are in a different branch of the same project is kind of strange. Also, those things they call "conrefs" are just "macros".
I think a macro implies something that can be executed, and (rightly) ought to cause security-minded folks to double-take. Conref isn't something we invented, it's straight out of DITA: http://dita.xml.org/arch-conref
That isn't true... Traditionally a macro just refers to a substitution, maybe (but not necessarily) with parameter replacement, rescanning, etc. I'd say that lisp-style macros which can execute arbitrary code are actually rather rare historically....
I personally found this write up extremely interesting and exciting. I have always been interested in documentation and its order in the priority list of tasks which a development team has to tackle. It is not an original observation that documentation is critically important to the success of a project/code-base and yet it is often the last artifact produced (and many skip it altogether). I have recently been extrem…
I found it recently, but it looks quite interesting.
I personally found this write up extremely interesting and exciting. I have always been interested in documentation and its order in the priority list of tasks which a development team has to tackle. It is not an original observation that documentation is critically important to the success of a project/code-base and yet it is often the last artifact produced (and many skip it altogether). I have recently been extrem…
I always thought it would be a good idea to generate API documentation from tests. Kind of the same idea you have but the other way around. The problem I used to have is that if you write your documentation by hand it tends to get out of sync with the code. You make a quick change to the code and forget to update the docs. After a while it's a mess unless you stay vigilant. But if you generate documentation from test…
