Late night discussion on software development #1: Continuous publishing

“So tell me”, I start, “when was the last time you used a help system?”

Søren pours himself another glass of red wine and leans back in his armchair. He is silent for a while. “What do you mean when you say help system?”

I open my mouth, and close it again. It always amazes me, when I realize the depth of such a seemingly naïve question. My immediate response seems too narrow. I have to break out of my standard way of thinking. A help system is not just a part of a larger system that helps you when you are stuck. It is even more than this. What comes out of my mouth is: “A help system is a system that helps you accomplish your tasks.”

“In that case I use help systems daily”, Søren proclaims.

“Really? I thought you already knew all the answers.”, I cannot resist the temptation.

Søren smiles, “You are also a developer, how do you manage to get anything done without a help system?”

Apparently Søren is into one of his moods where he answers all my questions with a new question. I sip my wine, take a deep breath and start to elaborate. “As a developer my work is quite dependent of the phase my project is in. Let's look at my favorite, the implementation phase. While writing code I never press the F1 button. I have worked with my current code editor for so long, that I’m fully aware of what it can and cannot do for me.”

Søren says: “So you have turned off IntelliSense?”

“No way – I don’t even know any developer crazy enough to do that. Actually I don’t even know an code editor that allows you to turn off IntelliSense.”

“Please go back to your definition of a help system.”

It dawns on me. Help system are more than just F1 help. It is anything that enables me to do my job. “Ok”, I say, “So what other help systems do you use?” I ask. I’m starting to feel confident I will earn more than a hangover from tonight.

“Well,” Søren says, “as a developer I often need to lookup API reference information. To do that I use the web constantly.”

“So you actually find any useful information out there? I’ve tried a few times but given up. Instead I browse objects locally searching for something that will satisfy my need.”

“That is one of the industry’s dilemmas. Users who have been disappointed by the documentation available in the help system, usually never come back. So why bother writing documentation, if it is not going to be read?“

“Exactly, if the documentation isn’t there, then there is no point in looking.”

Søren continues, “The users also suffers here, instead of looking for information where it is obvious they eagerly jump into the haystack looking for the needle. How can this destructive habit be reversed?”

A simple question, I think to myself. I answer: “Well, if the software providers just wrote the documentation we need, we wouldn’t have the problem.”

Søren promptly replies: “The question to ask is: How do you know it is not already there?” I feel like I’m being maneuvered into a corner. “When I installed my environment about 2 years ago, I browsed through the reference documentation, and it was primarily empty placeholders.”,  I pause to think about what I just said. “Naturally these placeholders might have been populated in the meantime.“ I make a mental note to  reserve some time on Monday morning to give the online documentation a second chance.

Søren finishes off his glass of red wine. He looks content.

Comments (3)

  1. RvB says:

    The F1 , or even the developer help shipped with AX is a great source of frustration. I’ve come to hate the ‘There is currently no information on this topc’ message for topics that *did* have info in 3.0

    On the other hand, the online docs on MSDN have been an invaluable resource.


  2. mugz says:

    I think there is one think to be a more stupid then having LOTS of placeholders in documentatuion – announce them in documentation updates.

    One more joke about Ax4 documentation:

    Question: How to find documentation for  the ‘beep’ function


    1. Go System DocumentationFunctionsbeep in AOT

    2. Open it

    3. Sorry… it is one more stub

    4. Press right mouse button and choose ‘Edit’ instead

    beep… beep… beep…

    PS. If you want, I can forward to you our conversiotion with David Pearlstein regarding this topic (stubs) 🙂

  3. twoelfer says:

    >> Søren finishes off his glass of red wine.

    i assume he did this while he was waiting for the "help system" to load, after he pressed F1.


    -thomas woelfer

Skip to main content