Do all the things like ++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatarSign Up
Get a devDuck
Rubber duck debugging has never been so cute! Get your favorite coding language devDuckBuy Now
Search - "documentation taught the wrong way"
it's funny, how doing something for ages but technically kinda the wrong way, makes you hate that thing with a fucking passion.
In my case I am talking about documentation.
At my study, it was required to write documentation for every project, which is actually quite logical. But, although I am find with some documentation/project and architecture design, they went to the fucking limit with this shit.
Just an example of what we had to write every time again (YES FOR EVERY MOTHERFUCKING PROJECT) and how many pages it would approximately cost (of custom content, yes we all had templates):
Phase 1 - Application design (before doing any programming at all):
- PvA (general plan for how to do the project, from who was participating to the way of reporting to your clients and so on - pages: 7-10.
- Functional design, well, the application design in an understandeable way. We were also required to design interfaces. (Yes, I am a backender, can only grasp the basics of GIMP and don't care about doing frontend) - pages: 20-30.
- Technical design (including DB scheme, class diagrams and so fucking on), it explains it mostly I think so - pages: 20-40.
Phase 2 - 'Writing' the application
- Well, writing the application of course.
- Test Plan (so yeah no actual fucking cases yet, just how you fucking plan to test it, what tools you need and so on. Needed? Yes. but not as redicilous as this) - pages: 7-10.
- Test cases: as many functions (read, every button click etc is a 'function') as you have - pages: one excel sheet, usually at least about 20 test cases.
Phase 3 - Application Implementation
- Implementation plan, describes what resources will be needed and so on (yes, I actually had to write down 'keyboard' a few times, like what the actual motherfucking fuck) - pages: 7-10.
- Acceptation test plan, (the plan and the actual tests so two files of which one is an excel/libreoffice calc file) - pages: 7-10.
- Implementation evalutation, well, an evaluation. Usually about 7-10 FUCKING pages long as well (!?!?!?!)
Phase 4 - Maintaining/managing of the application
- Management/maintainence document - well, every FUCKING rule. Usually 10-20 pages.
- SLA (Service Level Agreement) - 20-30 pages.
- Content Management Plan - explains itself, same as above so 20-30 pages (yes, what the fuck).
- Archiving Document, aka, how are you going to archive shit. - pages: 10-15.
I am still can't grasp why they were surprised that students lost all motivation after realizing they'd have to spend about 1-2 weeks BEFORE being allowed to write a single line of code!
Calculation (which takes the worst case scenario aka the most pages possible mostly) comes to about 230 pages. Keep in mind that some pages will be screenshots etc as well but a lot are full-text.
Yes, I understand that documentation is needed but in the way we had to do it, sorry but that's just not how you motivate students to work for their study!
Hell, students who wrote the entire project in one night which worked perfectly with even easter eggs and so on sometimes even got bad grades BECAUSE THEIR DOCUMENTATION WASN'T GOOD ENOUGH.
For comparison, at my last internship I had to write documentation for the REST API I was writing. Three pages, providing enough for the person who had to, to work with it! YES THREE PAGES FOR THE WHOLE MOTHERFUCKING PROJECT.
This is why I FUCKING HATE the word 'documentation'.36
OK, listen, this is not a lie.
For every sentence here, i collected a valid evendence i can show to proof, should you refuse to believe the sentence to be correct. Not one of the sentences down there is opinion but provable fact.
All of this is not a compendium of all mistakes i ever seen, but it is all present in ONE project:
- The codebase isn't a well thought out structure. In fact, it doesn't follow any defined standard, but is, instead, a bunch of spaghetti code. (provable by the fact that every class is public and globally visible)
- Where every one who worked at, failing to find or understand the existing code, added his personal universe of tools and objects. That despite that every class being globally visible. (provable by finding multiple implementations for same things)
- Also, it is remarkable that this happend even though the code is mostly young, the oldest parts only 3 years old and it still follows some or most of the major antipatterns there are. (provable by this was when the project started)
- There was not once a refactoring task issued in the runtime of that project. (provable by refactoring tasks not existing)
- Justified by just wrong reasoning like "it's optimised for mass data", or "it's how we work here, because it's always worked", the code does not follow
any design principles, let alone Michael Feathers and Robert C. Martins S-O-L-I-D principle, which is, while being taught and studied, improved and used in the rest of the world,
not even mentioned in one of the over 3000 pages of documents. (provable by full text search and asking the programmers about SOLID)
- Also, there is no state of the art Software Design process (provable by not having product owners, not having requirement engineers, nor design tools for that)
- nor is there distinction between business process and software solutiong in documentation, which, by the way has over 3200 pages (provable by having the functional documentation mixed with implementation details and process descriptions)
- There is no dev ops in place.
- Not a single Unit test has been created.
- The Code Inspection that could run at check in has been disabled.
- There is no dependency graph between packages
- There is no branching or encapsulation of changes nor association between code change and respecting task
- Everyone who works with that legacy code, where such a lot of things are not determinable, your check ins are a shot in the dark, provable by a direct correlation between commits, shortly followed by one-line commits to the same task.
- Also, it is internally communicated and believed there, that this is a high-end, object oriented, state of the art way of getting things done.
- Just yesterday, we stated an effort of 9 days (3 people work 3 days each) do let a modal dialog save the changes when coming back with OK Result.
- Also, training the existing programmers into transitioning to better software architecture and SOLID concepts is considered low priority because of it being too expensive4