- Lack of leadership in developer operations
- A lack of reporting of improvements in code reuse, coverage, test cases, and stability.
- Underutilization of frameworks and libraries used within the project.
- Lack of disposable runtime environments [for development and testing].
- Build times are unknown.
- Long and detailed documentation is required to build your product.
- Dead code is left in the code base to rot for years.
- Bugs are being reproduced as unit tests.
- Third Party dependencies are not being upgraded.
- Code is badly organized. Models are placed anywhere, packages aren’t organized, etc.
Tag Archives: documentation
A Few Signs That Your Project May Be In Some Serious Trouble
Posted by shicks
on 18 February 2013
5 comments
Getting Over Writer’s Block
Posted by shicks
on 11 February 2013
4 comments
A while ago, Tim Ferris was asked how he was able to accomplish the task of writing books of considerable length. The advice that he was given was: Write 2-3 sentences every day. I cannot recall who was the interviewer or the advisor. Note to the reader: It is possible to find this video on the internet, but I have no idea where it is. More help: It was after the 4 Hour Chef was released. This is great advice and has helped me. I have difficulty writing at times. When I’m faced with a large writing task I tend to become unmotivated. Writing two sentences is an easily accomplished task, reduces stress, and creates very manageable goals. This becomes incredibly helpful for when you are passionate about the subject, but your motivation for writing is lacking or your worry of getting your message across effectively is important. If you are extremely passionate about the subject I believe that you’ll find that after writing those two sentences your writing will transform into pages of text.
If only I knew this trick in college.
Additionally I don’t find that this trick works 100% of the time, but the writing becomes much easier when you create a framework for what is to be written beforehand. This is also true with writing code.
Don’t trust your Technical Documentation Staff to write Quickstart guides and Tutorials, Hire a Professional.
Posted by shicks
on 16 August 2012
3 comments
This is written with an audience of producers of software products/services in mind. Please do not claim that your documentation, used to introduce a new user/developer, is good enough to make the user/consumer (developer) proficient in your technology. Producers of software products [the developers, and organizations] are great at writing references to their products, however they generally are horrible at introducing new users to their product. When quick start guides, or introduction tutorials are written for products, the documentation tends to remain in the domain that the creators made. Solution: Hire a reputable technology writer. This will help you in a few ways:
- Gets a credible authority figure giving approval and backing to your technology
- Loses a creator bias
- The writer, like your audience, has an outside knowledge of other technologies
- They should not be influenced by the creators to write things that lack value to your actual users. (This assumes that sales and management cannot affect the contracted author’s work.)
- The users will understand the product better, and thus reduce undesirable support calls/emails.
- You will have professional documentation. The technical writer’s domain is to create attractive and easily consumable books, the software producer’s domain is not the same.
- From a business sense, the author is not a full time employee; they would remain as a short-term contract. Insulation from actual production is a good thing. This also helps the author as that it stabilizes their income streams.
- The documentation is written from a potential customer’s perspective
- It gives quick feedback on how easy the system, language, or product is to use, setup, troubleshoot, and possibly maintain.
Given these points, it would be easy to justify even a luxurious price on producing high quality introductions / non-referential documentation for your products. Based on these reasons, I conclude it would benefit the business professionals, developers, testers of the product, users, and the marketing department by separating the author him/herself from the general stress of the entire producing company.
Technical Writing for Programmers
Posted by shicks
on 30 March 2012
1 comment
Forewarning: I’m not an expert on this subject, however I do play one on television.
Software engineering is mostly a solitary, and technical occupation. Most of the non-programming language communication made by a developer is communicated to another person with domain, contextual, and similar technical knowledge. Very rarely, information is communicated to someone outside of the domain, or contextual atmosphere, let alone technical knowledge. This guide is more of a collection tips and reasons to document that I’ve discovered over the years.
- Acknowledge your audience. For frameworks, nothing is more frustrating to the reader when a quickstart guide is written for existing developers of that framework. Those developers do not want a quickstart guide, they want the Java/Net-doc. I’m looking at you Spring. If your audience is technical and new to your framework, please identify concepts that are exercised within the framework. Preferably, as an appendix and referenced to at the introduction of the book/document.
- Proof-read the document, even better: Have someone, even better people, from the targeted audience proof read the document for accuracy and readability. It is unbelievably surprising to discover how difficult it is to write documents that deal with troubleshooting, installation, configuration, or documentation of “common tasks.” From my experience, just the modification of an existing code base to add a new report took 4-5 pages of bullet point instructions. Once a documentation guide is published errors/incorrect documentation is embarrassing, are difficult to correct, and can be very costly.
- Screenshots: Screenshots make describing tasks involving a GUI clearer.
- Pictures [more than screenshots]: Reading words are useful, however a simple diagram is often useful for explaining complex architectures, or tasks. It also includes people who are visual learners.
- Versioning the document: This helps the user identify the document’s “up-to-date-ness.” I really hate advising this, as that some documents begin to include the change list. [Who really cares about this? All I want to know, as a reader, is if I have the most current version]
- If you are documenting source code and haven’t written by the time that you get to the unit test. Write the documentation while the tests are being written. If the documentation has already been written, write the unit tests based on that, even if you have access to the source code. From my experience this can piss off the original developer. However, as a tester, you should depend on the resources given to you, not what the actual structure is. From my experience, this level of pedantry can piss off the original developer, but in the long run it may prevent major errors in future reuse of the code. Make the unit test break if the documentation isn’t followed!!
- Provide documentation! Your developers/designers/user’s are very intelligent, however being intelligent does not make one a mind reader. Don’t expect another person to understand your [or your team's] motivation, history, design decisions, or politics surrounding the project.
- Allow for feedback. If there is mistake in the documentation, provide the user to contact the author of the documentation for confirmation of a mistake. If you don’t do this, expect for people to be pissed off about your API, idea, project, source code, or product.
- Document bugs or deprecation: If something doesn’t work or is going to be removed. Warn the developer. It’s better to know beforehand.
- Support: Support is more than a scripted technical support call. If you have better documentation low level support calls can be eliminated or substantially lessened. Additionally, supporting the documentation/product can give insight to the functionality used in the product and/or bugs that were previously not found.
- Job Security: It may sound contradicting (Most people I’ve talked to claim that obfuscation keeps a person employed for a while, at the expense of others), however it’s hard to claim that a person isn’t doing the job they were tasked with, or deny a promotion if their procedures are sufficiently documented.
- Documentation can help you identify architectural and interaction [GUI, and API] issues. This is more of a case of an problem, previously unrealized, coming into the consciousness. You’ve identified the issue, now you can talk about it and come up with a solution.
- For APIs: Provide examples for every method. Write a paragraph on: why someone should use that method, why one shouldn’t use it, the performance and memory costs, and the state change to the operation of the software or environment.
Have tips for technical writing, documentation? Leave them in the comments! [See I even provided feedback for this post 
]
