Detailed Notes
Welcome back to our series on the developer journey. In this episode, we tackle one of the most crucial yet often neglected aspects of development: the power of documentation. While it might seem tedious, proper documentation is vital to enhancing your workflow and ensuring that your work is accessible and understandable for others.
Read more... https://develpreneur.com/the-power-of-documentation-transforming-your-development-practices
Stay Connected: Join the Developreneur Community
We invite you to join our community and share your coding journey with us. Whether you’re a seasoned developer or just starting, there’s always room to learn and grow together. Contact us at [email protected] with your questions, feedback, or suggestions for future episodes. Together, let’s continue exploring the exciting world of software development.
Additional Resources
* Organizing Business Documentation: A Critical Challenge for Entrepreneurs (https://develpreneur.com/organizing-business-documentation-a-critical-challenge-for-entrepreneurs/)
* Test-Driven Development – A Better Object-Oriented Design Approach (https://develpreneur.com/test-driven-development-a-better-object-oriented-design-approach/)
* SDLC – The software development life cycle is simplified (https://develpreneur.com/sdlc-the-software-development-life-cycle-simplified/)
* Using a Document Repository To Become a Better Developer (https://develpreneur.com/using-a-document-repository-to-become-a-better-developer/)
Transcript Text
[Music] hey we hit record or something like that and we are are back and we're talking about our next episode and I think we're going to go with it we'll just do documentation you know wild wild west or something like that we'll just sort of see where we go with that because I think there's there's a there's a lot of places we can take it and there's a lot of places we need to take it so we'll see how this one goes and just sort of make that our our primary topic I think this this episode around well hello and welcome back we are continuing our season on the developer Journey we are here at developing nor building better developers the developer journey to becoming a better developer my name is Rob Broadhead I am one of the founders of develop rur I'm also a founder of RB Consulting where we we help Wrangle technology basically take that sprawl simplify it automate it integrate it whatever we need to do to get you to that big nasty thing that you had and now it's nice and sleep sleak and helps you get your job done faster we're like the iPod of Technology something along those lines on the other side is Michael and I'm going to go let ahead and let you introduce yourself hello everyone my name is Michael Mage I am one of the co-founders of developer Nur and founder of Envision QA where we help small to midsize companies and clinicians and Healthcare companies build software to meet their business needs as well as help them identify if the current technology they're using is what really is beneficial for their business this episode everybody's favorite topic as a developer documentation we're going to talk about that because everybody complains that they get something that wasn't documented but also nobody likes to document things and so now we know why nothing is that's why we complain all the time is because we don't do it nobody else does it so hey this is how you become a better developer is you do the things that nobody else wants to do a documentation is like testing to me a little bit is that it it has always been left behind it's one of those things like yeah it'd be great if we have it we know we should have it we know we should do it we a lot of times know how we should do it we just don't we run out of time but also in a similar vein is that the tools to help us document have come a long long long long way so we really need to be more cognizant of that at the very least understand what your environment language whatever it is what your tool provides in the way of documentation for example if you're writing apis and you don't know what Swagger is or those those types of tools then you need to like right now just pause Google it look it up you know Swagger with your API however you build it and they probably got 18,000 tutorials on how to set it up also if you don't know how to use Postman in your building apis pause go learn how to use Postman and actually Postman will help you do documentation so that's a side note there there are so many tools out there to help you straighten stuff out now there's going to be some things out there there's like there's static code analysis and things like that tools that are very valuable that will point to things they'll sort of like warn you here and there and they're going to be helpful for writing better code but more importantly or as importantly I would say are tools that auto help you autogenerate documentation stuff the old you know the I think it was really the first one that was out there if you go back to Java do and the ability to just like throw it against a a bunch of files and it just it creates a nice little documentation website there is the same same thing for every language out there that I know of I mean maybe not for like Cobalt or something but there probably still is something out there that'll do it and if not go write it because it's it's not that complicated to document things to a level that a tool like that can easily generate something that then makes it very very useful for the next person that comes around and by that I'm talking about things like your uh depending on how your your code is set out it's going to be things like classes and packages and signatures so you're going to know what does this return what does it expect what is the data types that this expects how does this thing even work what is it supposed to work what's the expectations what are the exceptions what are some of the error codes those things documenting those are critical those are the things that when somebody comes by two years from now and looking at your code that's the stuff they need to know it's like what the heck is this you got this thing called function ABC I don't know what that means give me some comments don't make me go through thousands of line of code to try to figure this out and then I miss a couple of side effects or something like that document it part of becoming a better developer is doing the things that documentation is a uh a sanity check for it's the kinds of things where you are if you're documenting your function and you know I need to document the inputs the outputs what are the side effects what are the data types what are the expectations then you should know what your stuff does for example if there's three different types of Errors then you should have somewhere in your code that it's going to kick out a different error code for each of those types of Errors don't make people find your source code and crawl through that and go searching for you know message text or something like that and try to figure out where this error is coming from those kinds of things are going to be invaluable to the next developer which could be somebody like you but also they're going to help you do a better job now it really is a like a yet another validation yet another testing form of testing to make sure that what you're writing is correct and of high quality now I'm going to sit back and document what I just said while Michael provides his own level of high quality stuff because I know You' got your your opinions on this as well so I want to see where's what's your feedback and where am I where am I right where am I wrong so without going too far on my soapbox of user testing and stories let me add to some of the things you said because I think you left off a few things you touched on most of the high points but one of the things that you didn't mention are readme files or markdown files files within the application that not just tell you how to test the application what the application is supposed to do but how you're supposed to set up the application in a test environment in a deployment environment how do you actually get this code from point A to point B so the users can actually use it we need to also think about that within our documentation so documentation isn't just front end it's pretty much all the way through you have the front end which is your user stories what is the application supposed to do what are the expectations uh what are some of the uh accepted uh test criteria what is the accepted test failures you know there's some things within it a version of code that might not be fully implemented yet so certain test Stories won't be ready to be tested so that you'll expect those to fail as you're going through and developing you're going to be developing with that expectation in mind that okay these stories should work this is what I'm coding to and when you hand it off to the testers they're going to look at it and say okay I'm expecting this have to work maybe this won't work and then they'll give you feedback and tell you what happened in between and then finally when it hands off to the users if you did it right you'll have release notes or product documentation that goes out to the users so when a the code comes out for the first time or an update comes out they can look at this and say okay how is this supposed to work so they can read through and it should match what the application does also if things change they should be able to look at the release notes and say okay this changed so if I go in here that's why I'm seeing this new feature or why is this new button here or why did this button disappear that should all be documented from the beginning to the end user you leave that out you're going to not set the expectation correctly for the end user and going to get a lot of negative calls emails or feedback that things are not working the way they're supposed to work so that is in addition to what you said now on top of what you said some of the things I like and one of the things um that in addition of the tools you mentioned we have things like bugzilla uh get Hub allows you to use uh a form of markdown or asky docs to actually write notation documentation that can be quickly converted into web uh nice easy to read web pages so you can actually publish that with your code some of the other things you can use are like um atlassian tools which gives you jira uh bit bucket Confluence so you cannot just write wikis but you can combine the wikis with the tickets the tickets with the wikis you can even uh take the bitbucket the your commits which can percolate all the way up to the tickets and all the way up to the wiki so if you do it right by the time you get to do a release or you publish your code your document may be self-published for you so all you have to do is include that with the release notes when you publish the code out the door and finally as you're going through this going back to our last discussion you want to include all the key players so as you're working on the documentation make sure that all the players involved have looked at or at least are aware of what changes are being done to the software so that by the end everyone is on the same page and you can do a signoff meeting of go no go if everything has been met or if issues have come up is it acceptable to let the code go out the door with changes to the documentation now that is very key is that you you will have more than one type of audience for your documentation and you will also have more than one type of documentation so I initially focused on the the code the developer but you do have the endusers you may have user you know online help or a user manual or something like that you will probably have depending on what the application is some sort of an administrator's guide so if there's somebody that's administering the system probably some sort of a build or deployment or install guide one of the things that that Michael like hit on early on is that you want to have a way to with your documentation you have to you want to be able to like plop this on somebody's desk or in their their computer and some way and for them to be able to go figure out how do I make this run how do I build it how do I deploy it how do I launch it what do I need what's required and one of the things that I've run into a lot when I'm you know when people haven't done that is is that there will be all of these little secondary scripts that or KRON jobs or things that are out there that are sometimes critical to the build but they're not documented anywhere and they're not in the main repository so check those things in keep that stuff together if you've got some little oneoff script that you used to migrate data from version one to version two and anybody else that's going down that route is going to need to do it then make sure that is somewhere documented whether you've got like a a documents or utilities or whatever kind of folder somewhere as part of that or if you have a second repository that is basically here's all of our stuff here's all of our artifacts for our for our application for our solution it is critical I mean it's it those are the things that it feels like everybody can figure that out like I I don't know how many times I've seen a node based app of some sort and they're just based just do a node run no there's like there's all kinds of libraries that maybe are part of that and maybe your environment isn't quite like the other so that would even be part of the testing is take your documentation take everything pick it up put it on a new environment Go spin up a VM do whatever you need to but take that whole thing put it on the environment follow the steps test the documentation does it run does it did you include all the usernames you need to and passwords you need to and what are all of these config all those configuration files that you probably have somewhere around there are those documented so people know what those values are and even more so what values don't even get used because we do have that on a regular basis and if you have something that's unused comment it out or do something ideally take it out but if if you for some reason need it there comment it out and say you know this I only had set here for testing or for this special bug or something like that you know those make sure that all of those little magical things that we do as we're developing to you know set things up in a certain way or to address a very specific bug things like that make sure we've got those documented along the way because that is the stuff that will drive the next person baddy if they don't have it particularly the build and I I say this having in the last 10 years I've got at least a half dozen projects where it was given to me the start was no idea how to build this no idea what all the pieces are we sort of think this is a source code but we don't even know if this is complete we've got these other things over here that we think are valuable but we don't really know it could be tied to another project that stuff shouldn't happen I don't care who you are I don't care where you're at in your in your career progression you should have some notes you should have something even if it's a couple emails that are just basically here's how this thing runs so that the next person can at least have a starting point I will kick it back over to you while I take a deep breath after that little bit so my final thought on that is regardless of where you're doing the documentation try to make sure that you move as much of the documentation to the code level at read me files add comments to the code if you're doing apis add Swagger but if you put it all at the code level especially if you're doing unit testing or integration testing in your code your test should also self document some of the user stories so if you do all your comments correctly at a push of a button you should be able to generate those documents you need for the release documents for the user documents for the deploy documents it's all at the code level this way as things change it gets committed and you have version history of what's going on with your code that's not to say using things like the wik and that are bad but at the end of the day the code is essentially the law the code is what is the truth everything else is secondary so if you put it in your code it should be your Bible this should be what it is that your code does so if you do it have a Wiki page it can get stale but if you do it all in a readme file you can still point the readme file to potentially the Swagger page if you're running locally QA whatever but you could still do it all in your code and then commit it and it's all there it's all at the ready so the next person that comes in should be able to easily pick it up it's great for training and it makes our lives easier as Developers yeah I like to think of it as you could if you've got your you know car and you've got a user's manual for your car there's a big difference from that user manual sitting in your office somewhere on a desk versus sitting in like the glove compartment of the car and that's often what happens we have all these little extra things sometimes big things that are external to our application but are core requirements and those things need to be documented somewhere it's things like hey this only runs on Windows 3.0 okay somebody needs to make sure that it needs Windows 3.0 those kinds of things should be you know there even if you don't include that entire environment in include those notes say these are the things you need to do to set up the environment for Success one the things you can do to set up our environment for success is to give us feedback is to send us emails at info@ developer.com leave us comments out on YouTube or out wherever you get your podcast or on develop andur on any of our articles anywhere we've got over a thousand articles out there feel free to throw stuff out there we will respond if it's a Spam we obviously won't we'll like delete it and move on but if it's something useful and for you guys I know it's going to be useful so you know reach out to us offer us any suggestions comments questions all of that kind of stuff that is what we look for because that is what we use to you know help build future episodes and even Seasons the season is not done we are chugging along but we are not done yet with the developer Journey so we will come back next time and we will continue to do that as always go out there and have yourself a great day a great week and we will talk to you next time all right bonus material so one addition which I saved for the bonus is well I talked about moving everything to the code level the beauty of doing that if you do it correctly you can actually write a script that can scan your readme files that can scan your uh markdown that can scan your aski docs and essentially build a user manual or deployment documentation for you from the code so once you're done and you're at the end of the cycle all you have to do is deploy your code your build script your continuous integration deployment whatever could call that script build all the documentation essentially self-publish when the code goes out the door so you could build hey here here's the signoff document this is everything that's going in in this release are we cool with this everyone signs off on it cool push the button goes forward it then automatically builds the release notes and the user documents at the end of the day so you can automate pretty much all of this people and if you do it right it can even tie to your user stories so if you create the user stories and your test cases correctly if you add a new test story that could apply to the final documentation of hey business this is now everything that we cover within our application yeah it does help a lot from a the closer you keep the documentation to code I think is this will be my little bonus this the better you're going to be as making sure that when you make code changes you're updating documentation particularly the documentation around the code and if you've done things right then that ends up percolating its way up so it may be things like um and I've seen this many times where you've got a a a primary requirements document that everybody put together but what you now have somewhere down the road is the requirements Document Plus you have release notes that have come out along the way that says okay we added this feature we added this fix we did this thing we did that thing if you can do those sorts of you know rituals basically when you do a deployment where it's like this is what we're going to we're going to run through this we build this we test this we verify this we generate that we stamp everything it gives you that road map to say where did you start from and how did you get here and you can track every B piece of it along the way which makes it critical then that's like huge for the next person because they can say hey I can not only see what you have but I can go back and see why you did it because that very often is something that if you don't have good documentation in a history of it those are kinds of things that can get lost and then people are like well why is this doing it why did they go this path why did they take that route and you you know you right there I know you right there you know that we do that stuff we have a a path we're going to take to make a solution to we're like this is how it's going to solve the problem and you realize something doesn't work that that perfect solution doesn't work for either because the problem's just a little bit off or because there's some sort of a an API version version which is one that's always good to know it's like hey I was going to solve this but Java 8 that I was working on would not allow this to happen it had a bug so when the next person comes back and they're now on Java 20 they can say hey this is why they didn't do it before so maybe we can do that now those are some of the things that are going to be really helpful to the next person around uh parting thoughts from you yeah so in addition to that that made me think of backend systems like apis so if you don't doent your apis correctly you could have apis that get deprecated or removed and if you don't communicate that to the end users or other software entities that integrate with your software you essentially break everything Downstream and that's going to make for a very unhappy user base I mean you don't want to be like the people we don't want to name from the news a few weeks ago but essentially you could end up in a situation like that so be careful make sure you document and make sure if there's a critical change that it does percolate to some type of documentation that goes out to the end user yeah and there because and th that's the stuff that's probably going to be the easiest to maintain because it's usually at a higher level so you don't have all those details but it really is amazing how many times I've walked into a project and be like I would kill for a user manual cuz I I don't know I'm not able to sit down and maybe with the users enough I'm not able to see what is this really supposed to do and sometimes that doesn't translate even from sometimes a fairly good requirements document if they don't have some good user stories and some things like that it's evolved into something that is used different from where it was and then it gets very difficult to understand like what's what's the why what is the purpose for this thing because it got lost in translation somewhere along the way one final thought on that typically think of the golden rule if you touch a piece of code make sure you leave it in a better place than where it was when you touched it and make sure that you leave the documentation to the whoever in a better place when you touch the code because you don't want to be the next person to come behind someone else who didn't do that and then you're lost and that's I say that's like one of the biggest values that you can bring to your customer when you when you get to that situation your customer your employer the project is okay it's gone off the rails but finding ways to bring it back on the rails finding ways to say okay this is what they had this is what was done this is how to do it better even if you can't fix all of it if you can just make it better than it was when you started that's at least progress in the right direction that being said I am going to progress to the right direction of moving on with my evening and Michael I think we'll do the same so as always feel free to leave us feedback however you can we'll be back here again as always come back next time around same time you're used to you will see us out there we'll have a new episode new podcast new uh new uh YouTube video to go with it and we're just going to keep chugging along and we've got we've got plenty I mean we may come back and just rant about documentation again but probably not we've got so many other things to rant about we'll move on to those in future episodes you guys go out there and have a good one and we will talk to you next time [Music]
Transcript Segments
[Music]
hey we hit record or something like that
and we are are back and we're talking
about our next
episode and I think we're going to go
with it we'll just
do documentation you know wild wild west
or something like that we'll just sort
of see where we go with that because I
think there's there's a there's a lot of
places we can take it and there's a lot
of places we need to take it so we'll
see how this one goes and just sort of
make that our our primary topic I think
this this episode around well hello and
welcome back we are continuing our
season on the developer Journey we are
here at developing nor building better
developers the developer journey to
becoming a better developer my name is
Rob Broadhead I am one of the founders
of develop rur I'm also a founder of RB
Consulting where we we help Wrangle
technology basically take that sprawl
simplify it automate it integrate it
whatever we need to do to get you to
that big nasty thing that you had and
now it's nice and sleep sleak and helps
you get your job done faster we're like
the iPod of Technology something along
those lines on the other side is Michael
and I'm going to go let ahead and let
you introduce
yourself hello everyone my name is
Michael Mage I am one of the co-founders
of developer Nur and founder of Envision
QA where we help small to midsize
companies and clinicians and Healthcare
companies build software to meet their
business needs as well as help them
identify if the current technology
they're using is what really is
beneficial for their
business this
episode everybody's favorite topic as a
developer documentation we're going to
talk about that because everybody
complains that they get something that
wasn't documented but also nobody likes
to document things and so now we know
why nothing is that's why we complain
all the time is because we don't do it
nobody else does it so hey this is how
you become a better developer is you do
the things that nobody else wants to do
a
documentation is like testing to me a
little bit is that it it has always been
left behind it's one of those things
like yeah it'd be great if we have it we
know we should have it we know we should
do it we a lot of times know how we
should do it we just don't we run out of
time but also in a similar vein is that
the tools to help us document have come
a long long long long way so we really
need to be more cognizant of that at the
very least understand what your
environment language whatever it is what
your tool provides in the way of
documentation for example if you're
writing apis and you don't know what
Swagger is or those those types of tools
then you need to like right now just
pause Google it look it up you know
Swagger with your API however you build
it and they probably got 18,000
tutorials on how to set it
up also if you don't know how to use
Postman in your building apis pause go
learn how to use Postman and actually
Postman will help you do documentation
so that's a side note
there there are so many tools out there
to help you straighten stuff out now
there's going to be some things out
there there's like there's static code
analysis and things like that tools that
are very valuable that will point to
things they'll sort of like warn you
here and there and they're going to be
helpful for writing better code but more
importantly or as importantly I would
say are tools that auto help you
autogenerate
documentation stuff the old you know the
I think it was really the first one that
was out there if you go back to Java do
and the ability to just like throw it
against a a bunch of files and it just
it creates a nice little documentation
website there is the same same thing for
every language out there that I know of
I mean maybe not for like Cobalt or
something but there probably still is
something out there that'll do it and if
not go write it because it's it's not
that complicated to document things to a
level that a tool like that can easily
generate something that then makes it
very very useful for the next person
that comes around and
by that I'm talking about things like
your uh depending on how your your code
is set out it's going to be things like
classes and packages and signatures so
you're going to know what does this
return what does it expect what is the
data types that this expects how does
this thing even work what is it supposed
to work what's the expectations what are
the exceptions what are some of the
error codes those
things documenting those are critical
those are the things that when somebody
comes by two years from now and looking
at your code that's the stuff they need
to know it's like what the heck is this
you got this thing called function ABC I
don't know what that means give me some
comments don't make me go through
thousands of line of code to try to
figure this out and then I miss a couple
of side effects or something like that
document it part of becoming a better
developer is doing the things that
documentation is a uh a sanity check for
it's the kinds of things where you are
if you're documenting your function and
you know I need to document the inputs
the outputs what are the side effects
what are the data types what are the
expectations then you should know what
your stuff does for example if there's
three different types of Errors then you
should have somewhere in your code that
it's going to kick out a different error
code for each of those types of Errors
don't make people find your source code
and crawl through that and go searching
for you know message text or something
like that and try to figure out where
this error is coming from those kinds of
things are going to be invaluable to the
next developer which could be somebody
like you but also they're going to help
you do a better job now it really is a
like a yet another validation yet
another testing form of testing to make
sure that what you're writing is correct
and of high quality now I'm going to sit
back and document what I just said while
Michael provides his own level of high
quality stuff because I know You' got
your your opinions on this as well so I
want to see where's what's your feedback
and where am I where am I right where am
I wrong so without going too far on my
soapbox of user testing and stories let
me add to some of the things you said
because I think you left off a few
things you touched on most of the high
points but one of the things that you
didn't mention are readme files or
markdown files files within the
application that not just tell you how
to test the application what the
application is supposed to do but how
you're supposed to set up the
application in a test environment in a
deployment environment how do you
actually get this code from point A to
point B so the users can actually use it
we need to also think about that within
our
documentation so documentation isn't
just front end it's pretty much all the
way through you have the front end which
is your user stories what is the
application supposed to do
what are the expectations uh what are
some of the uh accepted uh test criteria
what is the accepted test failures you
know there's some things within it a
version of code that might not be fully
implemented yet so certain test Stories
won't be ready to be tested so that
you'll expect those to fail as you're
going through and developing you're
going to be developing with that
expectation in mind that okay these
stories should work this is what I'm
coding to and when you hand it off to
the testers they're going to look at it
and say okay I'm expecting this have to
work maybe this won't work and then
they'll give you feedback and tell you
what happened in
between and then finally when it hands
off to the users if you did it right
you'll have release notes or product
documentation that goes out to the users
so when a the code comes out for the
first time or an update comes out they
can look at this and say
okay how is this supposed to work so
they can read through and it should
match what the application does also if
things change they should be able to
look at the release notes and say okay
this changed so if I go in here that's
why I'm seeing this new feature or why
is this new button here or why did this
button disappear that should all be
documented from the beginning to the end
user you leave that out you're going to
not set the expectation correctly for
the end user and going to get a lot of
negative calls emails or feedback that
things are not working the way they're
supposed to
work so that is in addition to what you
said now on top of what you said some of
the things I like and one of the things
um that in addition of the tools you
mentioned we have things like bugzilla
uh get Hub allows you to use uh a form
of markdown or asky docs to actually
write notation documentation that can be
quickly converted into web uh nice easy
to read web pages so you can actually
publish that with your code some of the
other things you can use are like um
atlassian tools which gives you jira uh
bit bucket Confluence so you cannot just
write wikis but you can combine the
wikis with the tickets the tickets with
the wikis you can even uh take the
bitbucket the your commits which can
percolate all the way up to the tickets
and all the way up to the wiki so if you
do it right by the time you get to do a
release or you publish your code your
document may be self-published for you
so all you have to do is include that
with the release notes when you publish
the code out the door and finally as
you're going through
this going back to our last
discussion you want to include all the
key players so as you're working on the
documentation make sure that all the
players
involved have looked at or at least are
aware of what changes are being done to
the software so that by the end everyone
is on the same page and you can do a
signoff meeting of go no go if
everything has been met or if issues
have come up is it acceptable to let the
code go out the door with changes to the
documentation now that is very key is
that you you will have more than one
type of audience for your documentation
and you will also have more than one
type of documentation so I initially
focused on the the code the developer
but you do have the endusers you may
have user you know online help or a user
manual or something like that you will
probably have depending on what the
application is some sort of an
administrator's guide so if there's
somebody that's administering the system
probably some sort of a build or
deployment or install guide one of the
things
that that Michael like hit on early on
is that you want to
have a way to with your documentation
you have to you want to be able to like
plop this on somebody's desk or in their
their computer and some way and for them
to be able to go figure out how do I
make this run how do I build it how do I
deploy it how do I launch it what do I
need what's required and one of the
things that I've run into a lot when I'm
you know when people haven't done that
is is that there will be all of these
little secondary scripts that or KRON
jobs or things that are out there that
are sometimes critical to the
build but they're not documented
anywhere and they're not in the main
repository
so check those things in keep that stuff
together if you've got some little
oneoff script that you used to migrate
data from version one to version two and
anybody else that's going down that
route is going to need to do it then
make sure that is somewhere documented
whether you've got like a a documents or
utilities or whatever kind of folder
somewhere as part of that or if you have
a second
repository that is basically here's all
of our stuff here's all of our artifacts
for our for our application for our
solution it is critical I mean it's it
those are the things that it feels like
everybody can figure that out like I I
don't know how many times I've seen
a node based app of some sort and
they're just based just do a node run no
there's like there's all kinds of
libraries that maybe are part of that
and maybe your environment isn't quite
like the other so that would even be
part of the testing is take your
documentation take everything pick it up
put it on a new environment Go spin up a
VM do whatever you need to but take that
whole thing put it on the environment
follow the steps test the documentation
does it run does it did you include all
the usernames you need to and passwords
you need to and what are all of these
config all those configuration files
that you probably have somewhere around
there are those documented so people
know what those values are and even more
so what values don't even get used
because we do have that on a regular
basis and if you have something that's
unused comment it out or do something
ideally take it out but if if you for
some reason need it there comment it out
and say you know this I only had set
here for testing or for this special bug
or something like that you know those
make sure that all of those
little magical things that we do as
we're developing to you know set things
up in a certain way or to address a very
specific bug things like that make sure
we've got those documented along the way
because that is the stuff that will
drive the next person baddy if they
don't have it particularly the build and
I I say this having in the last 10 years
I've got at least a half dozen projects
where it was given to me the start was
no idea how to build this no idea what
all the pieces are we sort of think this
is a source code but we don't even know
if this is complete we've got these
other things over here that we think are
valuable but we don't really know it
could be tied to another project that
stuff shouldn't happen I don't care who
you are I don't care where you're at in
your in your career progression you
should have some notes you should have
something even if it's a couple emails
that are just basically here's how this
thing runs so that the next person can
at least have a starting
point I will kick it back over to you
while I take a deep breath after that
little bit so my final thought on that
is regardless of where you're doing the
documentation try to make sure that you
move as much of the documentation to the
code level at read me files add comments
to the code if you're doing apis add
Swagger but if you put it all at the
code level especially if you're doing
unit testing or integration testing in
your code your test should also self
document some of the user stories so if
you do all your comments correctly at a
push of a button you should be able to
generate those documents you need for
the release documents for the user
documents for the deploy documents it's
all at the code level this way as things
change it gets committed and you have
version history of what's going on with
your code that's not to say using things
like the wik and that are bad but at the
end of the day the code is essentially
the law the code is what is the truth
everything else is secondary so if you
put it in your code it should be your
Bible this should be what it is that
your code does so if you do it have a
Wiki page it can get stale but if you do
it all in a readme file you can still
point the readme file to potentially the
Swagger page if you're running locally
QA whatever but you could still do it
all in your code and then commit it and
it's all there it's all at the ready so
the next person that comes in should be
able to easily pick it up it's great for
training and it makes our lives easier
as Developers
yeah I like to think of it as you could
if you've got your you know car and
you've got a user's manual for your car
there's a big difference from that user
manual sitting in your office somewhere
on a desk versus sitting in like the
glove compartment of the car and that's
often what happens we have all these
little extra things sometimes big things
that are external to our application but
are core requirements and those things
need to be documented somewhere it's
things like hey this only runs on
Windows 3.0 okay somebody needs to make
sure that it needs Windows 3.0 those
kinds of things should be you know there
even if you don't include that entire
environment in include those notes say
these are the things you need to do to
set up the environment for
Success one the things you can do to set
up our environment for success is to
give us feedback is to send us emails at
info@ developer.com leave us comments
out on YouTube or out wherever you get
your podcast or on develop andur on any
of our articles anywhere we've got
over a thousand articles out there feel
free to throw stuff out there we will
respond if it's a Spam we obviously
won't we'll like delete it and move on
but if it's something useful and for you
guys I know it's going to be useful so
you know reach out to us offer us any
suggestions comments questions all of
that kind of stuff that is what we look
for because that is what we use to you
know help build future episodes and even
Seasons the season is not done we are
chugging along but we are not done yet
with the developer Journey
so we will come back next time and we
will continue to do that as always go
out there and have yourself a great day
a great week and we will talk to you
next
time all right bonus material so one
addition which I saved for the bonus is
well I talked about moving everything to
the code level the beauty of doing that
if you do it correctly you can actually
write a script that can scan your readme
files that can scan your uh markdown
that can scan your aski docs and
essentially build a user manual or
deployment documentation for you from
the code so once you're done and you're
at the end of the cycle all you have to
do is deploy your code your build script
your continuous integration deployment
whatever could call that script build
all the documentation essentially
self-publish when the code goes out the
door so you could build hey here here's
the signoff document this is everything
that's going in in this
release are we cool with this everyone
signs off on it cool push the button
goes forward it then automatically
builds the release notes and the user
documents at the end of the day so you
can automate pretty much all of this
people and if you do it right it can
even tie to your user stories so if you
create the user stories and your test
cases correctly if you add a new test
story that could apply to the final
documentation of hey business this is
now everything that we cover within our
application yeah it does help a lot from
a the closer you keep the documentation
to code I think is this will be my
little bonus this the better you're
going to be as making sure that when you
make code changes you're updating
documentation particularly the
documentation around the code and if
you've done things right then that ends
up percolating its way up so it may be
things like um and I've seen this many
times where you've got a a a primary
requirements document that everybody put
together but what you now have somewhere
down the road is the requirements
Document Plus you have release notes
that have come out along the way that
says okay we added this feature we added
this fix we did this thing we did that
thing if you can do those sorts of you
know rituals basically when you do a
deployment where it's like this is what
we're going to we're going to run
through this we build this we test this
we verify this we generate that we stamp
everything it gives you that road map to
say where did you start from and how did
you get here and you can track every B
piece of it along the way which makes it
critical then that's like huge for the
next person because they can say hey I
can not only see what you have but I can
go back and see why you did it because
that very often is something that if you
don't have good documentation in a
history of it those are kinds of things
that can get lost and then people are
like well why is this doing it why did
they go this path why did they take that
route and you you know you right there I
know you right there you know that we do
that stuff we have a a path we're going
to take to make a
solution to we're like this is how it's
going to solve the problem and you
realize something doesn't work that that
perfect solution doesn't work for either
because the problem's just a little bit
off or because there's some sort of a an
API version version which is one that's
always good to know it's like hey I was
going to solve this but Java 8 that I
was working on would not allow this to
happen it had a bug so when the next
person comes back and they're now on
Java 20 they can say hey this is why
they didn't do it before so maybe we can
do that now those are some of the things
that are going to be really helpful to
the next person around uh parting
thoughts from you yeah so in addition to
that that made me think of backend
systems like apis so if you don't doent
your apis correctly you could have apis
that get deprecated or removed and if
you don't communicate that to the end
users or other software entities that
integrate with your software you
essentially break everything Downstream
and that's going to make for a very
unhappy user base I mean you don't want
to be like the people we don't want to
name from the news a few weeks ago but
essentially you could end up in a
situation like that so be careful make
sure you document and make sure if
there's a critical change that it does
percolate to some type of documentation
that goes out to the end
user yeah and there because and th
that's the stuff that's probably going
to
be the easiest to maintain because it's
usually at a higher level so you don't
have all those details but it really is
amazing how many times I've walked into
a project and be like I would kill for a
user manual cuz I I don't know I'm not
able to sit down and maybe with the
users enough I'm not able to see what is
this really supposed to do and sometimes
that doesn't translate even from
sometimes a fairly good requirements
document if they don't have some good
user stories and some things like that
it's evolved into something that is used
different from where it was and then it
gets very difficult to understand like
what's what's the why what is the
purpose for this thing because it got
lost in translation somewhere along the
way one final thought on
that typically think of the golden rule
if you touch a piece of code make sure
you leave it in a better place than
where it was when you touched it and
make sure that you leave the
documentation to the whoever in a better
place when you touch the code because
you don't want to be the next person to
come behind someone else who didn't do
that and then you're
lost and that's I say that's like one of
the biggest values that you can bring to
your customer when you when you get to
that situation your customer your
employer the project is okay it's gone
off the rails but finding ways to bring
it back on the rails finding ways to say
okay this is what they had this is what
was done this is how to do it better
even if you can't fix all of it if you
can just make it better than it was when
you started that's at least progress in
the right
direction that being said I am going to
progress to the right direction of
moving on with my evening and Michael I
think we'll do the same so as always
feel free to leave us feedback however
you can we'll be back here again as
always come back next time around same
time you're used to you will see us out
there we'll have a new episode new
podcast new uh new uh YouTube video to
go with it and we're just going to keep
chugging along and we've got we've got
plenty I mean we may come back and just
rant about documentation again but
probably not we've got so many other
things to rant about we'll move on to
those in future episodes you guys go out
there and have a good one and we will
talk to you next time
[Music]