I once worked on a Finance project which had grand aspirations and decided it was going to Do Things Right by starting with extensive specifications.
The developers insisted on all behaviour being specified and documented before they would start coding. Of course, a truly exacting specification is equivalent to code. So the users who had been tasked with describing the required functionality ended up inventing their own DSL and “coding” the entire system in Microsoft Word.
Needless to say, they were the only ones who understood the spec. IT cried foul. Business cried “this is what you asked for!”
Cue months of arguments over what constituted a proper spec, during which the users essentially taught themselves how to code. The software eventually ended up being written by transliterating the DSL into actual code.
It worked, but remains to this day an unmaintainable mess.
So the documentation was simply incomplete, because the DSL, as a language, was not documented properly. This is why the initial developers were unable to have it maintained by others.
Essentially the same problem, just on a higher level of abstraction.
Oh, and failing to document DSLs is really a common mistake: No docs, no spec, no helpful error messages, and so on. Just like the very early parsers or compilers. But DSLs are really the most important thing to document, as these are so much harder to get into ... the "simpler" parts of the program are usually readable and understandable with less effort, even with pure code and no docs at all.
Well, the DSL flowed out of documenting the problem. Having non-technical people write a DSL, and then proceed to document that DSL, is not really addressing the core problem which was knowledge transferrence. Why do you feel they'd be better able to document a DSL than they were documenting the domain?
The whole purpose of a DSL is to make the whole system simpler, by separation of concerns.
That is, the DSL as a language is still much simpler (fewer data types, fewer elements, fewer rules, etc.) than the whole application, which is built using that DSL.
So I'd expect the DSL's documentation to be short and targeted at the people writing within that DSL.
If the DSL's documentation is more complicated than the original problem (spec), it failed at its purpose.
BTW, ultimately you have a chain of languages, such as:
Spec <- DSL <- Meta-DSL <- ... <- programing language
But in the end, that chain goes from complex/specific to simpler/generic. So the documentation effort should shrink dramatically from one step to another (or your system design is seriously flawed). Usually, the Meta-DSL or Meta-Meta-DSL is already the plain, generic programming language you are using. And that one requires no documentation writing at all, because is already documented and widely understood.
Indeed, usually these approaches are abandoned due to reaching a point where arguments over specifications consume years and nothing happens. The project is killed and everyone involved are reassigned elsewhere, hopefully having learned something, but usually there's no such evidence of learning.
In all fairness, it's not entirely obvious that this is how to do it.
But it's a good tip nonetheless. Once you click the "x minutes/hours/days ago" link, besides bookmarking the resulting URL in your browser or elsewhere, you also have a few more options that show up at the top of the comment page. One of them is to "favorite" the comment. You can also favorite a submission in a similar way.
Just be advised that your favorite submissions and comments lists are public.
> it's not entirely obvious that this is how to do it
I totally agree that this is an example of insane, hidden functionality. How could anyone know that "click timestamp" = "view details"? Makes no sense.
However, seemingly every site/app has adopted this, from Twitter to Facebook to several PM services.
OK, so on HN, it's clickable. But "gray text without underline" isn't always clickable on HN. This is true of other sites: it isn't even clear that the timestamp is clickable at all, let alone what'll happen if you do click it.
Why not acknowledge that this is a problem and just add a little "Permalink" link, which some sites used to have? Or at least a permalink icon?
Surely the combined design talent of Google, Facebook, and Twitter can solve this problem better.
I think hidden is not quite the right word. It's a link, likely displayed in a hypertext browser.
A hypertext system that doesn't treat links as slightly opaque, explaining them in detail wherever they appear, sounds unpleasant to me.
I guess you could probably modify most such systems to have a flashing popup on every link that said "There is more information available if you click on the text here!!!!".
> It worked, but remains to this day an unmaintainable mess.
The question is: is it a worse mess than if you'd have started without the spec? My intuition says "no", and the experience the users gained regarding formal thinking is a huge net benefit that will be an asset for years to come.
The developers insisted on all behaviour being specified and documented before they would start coding. Of course, a truly exacting specification is equivalent to code. So the users who had been tasked with describing the required functionality ended up inventing their own DSL and “coding” the entire system in Microsoft Word.
Needless to say, they were the only ones who understood the spec. IT cried foul. Business cried “this is what you asked for!”
Cue months of arguments over what constituted a proper spec, during which the users essentially taught themselves how to code. The software eventually ended up being written by transliterating the DSL into actual code.
It worked, but remains to this day an unmaintainable mess.