#DevDiscuss Archive

Tuesday March 28, 2017
9:00 PM EDT
  • ThePracticalDev Mar 28 @ 9:00 PM EDT
    Welcome to the #DevDiscuss Twitter chat, tonight's topic is documentation.
  • ThePracticalDev Mar 28 @ 9:02 PM EDT
    Rules: - Stay on topic - ALWAYS ALWAYS use hashtag #DevDiscuss - Be NICE/POSITIVE ❤️ - Quoting tweets for clarity is encouraged
  • charlesj Mar 28 @ 9:05 PM EDT
    Documentation should be version controlled with the code, not separate. Definition of Done includes updating documentation.#DevDiscuss
  • leftynaut Mar 28 @ 9:06 PM EDT
    #DevDiscuss If you're new to documentation, this template will cover the important parts: https://t.co/YPd6qJLN7Y
  • ThePracticalDev Mar 28 @ 9:06 PM EDT
    Why is technical documentation important? Can't I just write readable code? #devdiscuss
  • camofclay Mar 28 @ 9:06 PM EDT
    #devdiscuss how do you encourage teammates to document their work?
    In reply to @ThePracticalDev
  • mrm8488 Mar 28 @ 9:06 PM EDT
    in our SCRUM team, to be able to say you have finished a STORY, one of our ACs was updating docs #DevDiscuss
    In reply to @ThePracticalDev
  • tblodt Mar 28 @ 9:07 PM EDT
    Because nobody wants to read your code, no matter how nice it looks. Sorry. #DevDiscuss
    In reply to @ThePracticalDev
  • tblodt Mar 28 @ 9:07 PM EDT
    Because nobody wants to read your code, no matter how nice it looks. Sorry. #DevDiscuss
  • Programazing Mar 28 @ 9:08 PM EDT
    I can honestly say I haven't written much documentation other than trying to make my code very readable. #DevDiscuss
  • EricSchillerDev Mar 28 @ 9:09 PM EDT
    Readable code to handle messy business processes is no longer readable. Document the hard stuff. #devdiscuss
    In reply to @ThePracticalDev
  • yechielk Mar 28 @ 9:10 PM EDT
    @ThePracticalDev all you need to do is look at "readable" code you wrote a month ago to see why... #devdiscuss
    In reply to @ThePracticalDev
  • mrskellyvaughn Mar 28 @ 9:10 PM EDT
    Documentation doubles as a learning opportunity. Why did you code something the way you did? How may it be reused in the future? #DevDiscuss
  • aaroneiche Mar 28 @ 9:10 PM EDT
    Docs are hard. They're (IMO) the least creative part of programming. Engineers don't find them fulfilling #Devdiscuss
    In reply to @ThePracticalDev
  • silenceofnight Mar 28 @ 9:10 PM EDT
    @ThePracticalDev #devdiscuss Readable code -> I understand what it is doing. Documentation -> I understand why it does that.
    In reply to @ThePracticalDev
  • jayrav13 Mar 28 @ 9:10 PM EDT
    Reading linearly in English/any language is much easier than decoding code that's all over! Super timely, worked on some today! #devdiscuss
  • mrskellyvaughn Mar 28 @ 9:10 PM EDT
    Knowing how to code is one thing. Knowing WHY you coded something the way you did is even better. #DevDiscuss
  • kylewelch Mar 28 @ 9:10 PM EDT
    One of the biggest thing code lack (even clean code) is the decision process. #DevDiscuss
  • billperegoy Mar 28 @ 9:11 PM EDT
    Documentation outside of code is almost always out of date or inaccurate. I’d much prefer good code. #devdiscuss
    In reply to @ThePracticalDev
  • practicingdev Mar 28 @ 9:11 PM EDT
    Won't have have time to join the #devdiscuss chat tonight but published a *super* relevant article last week: https://t.co/SvbOe2MDJP
  • kylewelch Mar 28 @ 9:11 PM EDT
    To expand on this, our code base as some comments that say, "This is not right, but it is what they wanted" #DevDiscuss
  • tremendous3 Mar 28 @ 9:11 PM EDT
    APIs are used by clients, customers, other developers. Technical documentation helps your product and concepts spread. #devdiscuss
  • aaroneiche Mar 28 @ 9:11 PM EDT
    Did you find that it is motivating enough to finish a story? #DevDiscuss
    In reply to @mrm8488, @ThePracticalDev
  • voxcpw Mar 28 @ 9:12 PM EDT
    Documentation should answer the why. That's why it's so hard to write well, because why changes and evolves. #devdiscuss
  • ThePracticalDev Mar 28 @ 9:12 PM EDT
    ❤️ #devdiscuss
    In reply to @practicingdev
  • kylewelch Mar 28 @ 9:12 PM EDT
    Another good use of technical documentation is to show arch decision or explain compromises. #DevDiscuss
  • jayrav13 Mar 28 @ 9:12 PM EDT
    so true - started API docs for a service I'm writing right now and it helped me challenge my own decisions! #devdiscuss
    In reply to @mrskellyvaughn
  • levhita Mar 28 @ 9:12 PM EDT
    Documentation is best Live. for example handling database structure with MySQL Workbench and Sync It with server and devs #DevDiscuss
  • hawkinjs Mar 28 @ 9:12 PM EDT
    better docs => better contribs /easier use. Different minds read differently. Help us see *your* interpretation #DevDiscuss
    In reply to @ThePracticalDev
  • MiffPengi Mar 28 @ 9:13 PM EDT
    Documentation is for figuring out how to use the code, reading the code is for figuring out how it works. @ThePracticalDev #devdiscuss
    In reply to @ThePracticalDev
  • SadITGuy Mar 28 @ 9:14 PM EDT
    Tonight, on Unintentional Alliteration: #DevDiscuss
  • levhita Mar 28 @ 9:14 PM EDT
    Vagrant or Docker scripts are also a very good example of Live documentation, That is runned and tested everyday #DevDiscuss
  • sxldvd Mar 28 @ 9:15 PM EDT
    #DevDiscuss I started my open source journey (few days ago) by contributing on #documentation. Do not hesitate to fix, add infos.
  • jayrav13 Mar 28 @ 9:15 PM EDT
    For API's check out @rl0rd's docs below. They're awesome! (sorry for the multiple tags recently 😅)! #devdiscuss https://t.co/bG5GUp9jKx
  • kylewelch Mar 28 @ 9:15 PM EDT
    Another document I have been working lately is, "why does it differ from our current standard/practice" #DevDiscuss
    In reply to @mrskellyvaughn
  • philibertdugas Mar 28 @ 9:17 PM EDT
    Documentation helps to understand the big lines. Code clarifies the details #devdiscuss
  • twobree Mar 28 @ 9:18 PM EDT
    Even if it's for yourself, documentation includes gotchas you ran into, how you solved them, and "whys" behind your decisions #devdiscuss
  • levhita Mar 28 @ 9:19 PM EDT
    There are standards to document APIs generated directly from source code comments and structure, live documentation everywhere! #DevDiscuss
  • wesjd_ Mar 28 @ 9:19 PM EDT
    code is more than just what it says. it's what it creates. readable code != documented code. #devdiscuss https://t.co/jJyQ5GVkKH
  • jayrav13 Mar 28 @ 9:20 PM EDT
    Because others have to carry on what you begin. My goal - if someone can build a project locally w/out my input, my docs work. #devdiscuss
  • twobree Mar 28 @ 9:20 PM EDT
    Docs are very helpful to those unfamiliar with your code. But you'd be surprised​ hope useful they are to your workflow #devdiscuss
  • mrm8488 Mar 28 @ 9:20 PM EDT
    that's not about motivation is just one acceptance criteria that the team accord before a project to improve qlity #DevDiscuss
    In reply to @aaroneiche
  • lilymercy Mar 28 @ 9:20 PM EDT
    it will give a clear understanding of your code #devdiscuss
    In reply to @ThePracticalDev
  • davidbrunelle Mar 28 @ 9:20 PM EDT
    Ideally you write "just enough" documentation to describe what the code and tests cannot. The right amount is subjective. #devdiscuss
  • ThePracticalDev Mar 28 @ 9:20 PM EDT
    HOW do you document a project, where do the docs live, what guidelines/services/tools help you with your docs? #devdiscuss
  • twobree Mar 28 @ 9:21 PM EDT
    Docs aren't about explaining your code line by line, even if that's what they teach in school. It's all about commination intent #devdiscuss
  • aaroneiche Mar 28 @ 9:21 PM EDT
    I appreciate that - My experience is that projects will push aside criteria when facing deadline, or other distractions #DevDiscuss
    In reply to @mrm8488
  • kylewelch Mar 28 @ 9:21 PM EDT
    I agree, documentation is rubber-ducky-ing on "paper". It has the added benefit that not everyone reads code. #DevDiscuss
    In reply to @twobree
  • NickHansen600 Mar 28 @ 9:22 PM EDT
    probably not #DevDiscuss
    In reply to @ThePracticalDev
  • lucus_patrick Mar 28 @ 9:23 PM EDT
    a good test of your code if it actually does what you intended/ documented it to do #devdiscuss
    In reply to @ThePracticalDev
  • billperegoy Mar 28 @ 9:23 PM EDT
    I judge a project by its README. If I can’t start developing quickly,I suspect I’ll dislike the code too. #devdiscuss
    In reply to @ThePracticalDev
  • jayrav13 Mar 28 @ 9:23 PM EDT
    If I have multiple apps that work together, I might actually create a separate web app that's JUST documentation. #devdiscuss
    • ThePracticalDev Mar 28 @ 9:20 PM EDT
      HOW do you document a project, where do the docs live, what guidelines/services/tools help you with your docs? #devdiscuss
  • twobree Mar 28 @ 9:23 PM EDT
    We maintain a company wiki in Gitlab about bugs, gotchas, retrospectives, internal patterns... No other tools right now #devdiscuss
    • ThePracticalDev Mar 28 @ 9:20 PM EDT
      HOW do you document a project, where do the docs live, what guidelines/services/tools help you with your docs? #devdiscuss
  • justAfanDavid Mar 28 @ 9:23 PM EDT
    #devdiscuss oh man, I wish I had the time to list out the reasons docs are important...just trust me ;-)
    In reply to @ThePracticalDev
  • kylewelch Mar 28 @ 9:24 PM EDT
    Currently wrote up a doc standard to have a ReadMe for project level docs, then a docs folder w/ specialized/technical docs #DevDiscuss
    • ThePracticalDev Mar 28 @ 9:20 PM EDT
      HOW do you document a project, where do the docs live, what guidelines/services/tools help you with your docs? #devdiscuss
  • BinaryIdiot Mar 28 @ 9:24 PM EDT
    Where possible always try to generate documentation based off of code to avoid stale comments. I try to do this as much as I can #DevDiscuss
    • ThePracticalDev Mar 28 @ 9:20 PM EDT
      HOW do you document a project, where do the docs live, what guidelines/services/tools help you with your docs? #devdiscuss
  • philibertdugas Mar 28 @ 9:24 PM EDT
    Markdown is 👌 for documentation #devdiscuss
    • ThePracticalDev Mar 28 @ 9:20 PM EDT
      HOW do you document a project, where do the docs live, what guidelines/services/tools help you with your docs? #devdiscuss
  • lucus_patrick Mar 28 @ 9:24 PM EDT
    wiki-style docs are my pref. A living document, adding small amounts during the progression of the project #devdiscuss
    In reply to @ThePracticalDev
  • mrm8488 Mar 28 @ 9:25 PM EDT
    if you can finish a story due to deadlines or other distractions, don't do it.But ensure the qty of finishd stories.#DevDiscuss
    In reply to @aaroneiche
  • BinaryIdiot Mar 28 @ 9:25 PM EDT
    Naturally this can lead to documentation that isn't very intuitive to read so try to include personable descriptions in code #DevDiscuss
    • BinaryIdiot Mar 28 @ 9:24 PM EDT
      Where possible always try to generate documentation based off of code to avoid stale comments. I try to do this as much as I can #DevDiscuss
      • ThePracticalDev Mar 28 @ 9:20 PM EDT
        HOW do you document a project, where do the docs live, what guidelines/services/tools help you with your docs? #devdiscuss
  • jayrav13 Mar 28 @ 9:26 PM EDT
    my internship mgr told me "you're the product manager of what you build - sell it" #devdiscuss
    In reply to @billperegoy, @ThePracticalDev
  • dexterhaslem Mar 28 @ 9:26 PM EDT
    good static site generator like hugo w/ good templates and partials, then require docs in PRs #devdiscuss
    In reply to @ThePracticalDev
  • mrm8488 Mar 28 @ 9:26 PM EDT
    you will plan better on next sprint and reach a better arrange with the PO. But quality first #DevDiscuss
    In reply to @aaroneiche
  • jayrav13 Mar 28 @ 9:26 PM EDT
    a part of that from a tech perspective was how well someone can follow what you're doing, so true. #devdiscuss
    In reply to @billperegoy, @ThePracticalDev
  • davidbrunelle Mar 28 @ 9:28 PM EDT
    I strongly advocate colocating docs (and tests) with code. It helps protect against drift between docs and implementation #devdiscuss
    • ThePracticalDev Mar 28 @ 9:20 PM EDT
      HOW do you document a project, where do the docs live, what guidelines/services/tools help you with your docs? #devdiscuss
  • sxldvd Mar 28 @ 9:28 PM EDT
    Documentation helps you understand the theoretical aspects hidden behind a simple fuction for ex. #DevDiscuss
  • twobree Mar 28 @ 9:29 PM EDT
    #devdiscuss Start w stubs + brain dumps. Then "fill in those gaps, and the gaps between the gaps" - @practicingdev https://t.co/vV1QWNiLDa
    In reply to @practicingdev
  • lilymercy Mar 28 @ 9:31 PM EDT
    markdown cheat sheet guideline help in writing docs #devdiscuss
    In reply to @ThePracticalDev
  • levibostian Mar 28 @ 9:32 PM EDT
    My docs: https://t.co/K2qsd2jki1. I use PeachDocs https://t.co/KqX0Y4G6De. Markdown, Git publish, customize. #DevDiscuss
    In reply to @ThePracticalDev
  • gosub_10 Mar 28 @ 9:33 PM EDT
    Would you read RabbitMQ code in order to configure it or use it? No, you need the docs. #devdiscuss
    In reply to @ThePracticalDev, @ThePracticalDev
  • kylewelch Mar 28 @ 9:33 PM EDT
    Tests can easily double as documentation and provide simple use cases. Don't loss out of this opportunity #DevDiscuss
    In reply to @davidbrunelle
  • billperegoy Mar 28 @ 9:33 PM EDT
    Docs written while during development are better than specs written before coding begins. Same with docs written after the fact. #devdiscuss
  • gumnos Mar 28 @ 9:34 PM EDT
    Different docs live different places • inline docs→in code • longform userdocs→in docs/ • devdocs→src/docs/ #devdiscuss
    In reply to @davidbrunelle
  • gumnos Mar 28 @ 9:35 PM EDT
    But they all live within source control. #devdiscuss
    In reply to @davidbrunelle
  • FCPaulDiaz Mar 28 @ 9:35 PM EDT
    API docs on @SwaggerApi #devdiscuss
    In reply to @ThePracticalDev, @SwaggerApi
  • ThePracticalDev Mar 28 @ 9:36 PM EDT
    What is best, writing documentation before, during, or after writing code? And besides best practice, what do YOU do? #DevDiscuss
  • davidbrunelle Mar 28 @ 9:36 PM EDT
    see my last #devdiscuss tweet. :-)
    In reply to @kylewelch
  • gumnos Mar 28 @ 9:36 PM EDT
    Perceived readability is always less than expected readability. So aim higher when writing docs. 🙂 #devdiscuss
    In reply to @gturner, @ThePracticalDev
  • jrgifford Mar 28 @ 9:36 PM EDT
    Dayjob, confluence. Side project, GitHub Wiki. Works well and lets us be verbose. Confluence has added bonus of comment system. #devdiscuss
  • KathyApplebaum Mar 28 @ 9:36 PM EDT
    Our code base is a couple million lines. No one dev knows it all -- docs are the roadmap that gets us to the readable code. #devdiscuss
    In reply to @ThePracticalDev
  • UnfairDaniel Mar 28 @ 9:37 PM EDT
    My docs start in code. Every function/class/method/property gets a how(to use it)/what(it does)/why(it exists) #devdiscuss
    In reply to @ThePracticalDev
  • billperegoy Mar 28 @ 9:37 PM EDT
    writing docs before coding == waterfall. It’s always out of date #devdiscuss
    In reply to @ThePracticalDev
  • kylewelch Mar 28 @ 9:37 PM EDT
    I have started documenting rough notes as I learn or start something. Then structure once I understand it all #DevDiscuss
    • ThePracticalDev Mar 28 @ 9:36 PM EDT
      What is best, writing documentation before, during, or after writing code? And besides best practice, what do YOU do? #DevDiscuss
  • gumnos Mar 28 @ 9:37 PM EDT
    I treat my tests like documentation for other devs (coughmecough) on how to interface with my code. #devdiscuss
    In reply to @kylewelch, @davidbrunelle
  • twobree Mar 28 @ 9:38 PM EDT
    It really depends on what you're writing about and how certain you are off certain parts. Is scope likely to change as you code? #devdiscuss
    • ThePracticalDev Mar 28 @ 9:36 PM EDT
      What is best, writing documentation before, during, or after writing code? And besides best practice, what do YOU do? #DevDiscuss
  • billperegoy Mar 28 @ 9:38 PM EDT
    Docs written after development are usually half-hearted attempts to meet some management requirement. #devdiscuss
    In reply to @ThePracticalDev
  • twobree Mar 28 @ 9:39 PM EDT
    In agile etc development, things can change quickly before a final release, so docs may be better after. #devdiscuss
  • gumnos Mar 28 @ 9:39 PM EDT
    fossil (a git alternative) has built-in wiki and bug-tracking. I wish git offered such. #devdiscuss
    In reply to @samvbeckmann, @ThePracticalDev
  • jayrav13 Mar 28 @ 9:39 PM EDT
    Best - consistently during. Practical - I don't keep up 😅😂. I get ~80% of the way through before going back and catching up! #devdiscuss
    • ThePracticalDev Mar 28 @ 9:36 PM EDT
      What is best, writing documentation before, during, or after writing code? And besides best practice, what do YOU do? #DevDiscuss
  • lilymercy Mar 28 @ 9:39 PM EDT
    I prefer writing doc after writing code. #devdiscuss
    In reply to @ThePracticalDev
  • kylewelch Mar 28 @ 9:40 PM EDT
    Honestly, when I am learning something new or reviewing code it is the firs thing I look for. #devdiscuss @davidbrunelle
    In reply to @gumnos, @davidbrunelle
  • twobree Mar 28 @ 9:40 PM EDT
    But in more formal projects with waterfall Dev and consecutive stages, docs before each stage may help when working on the next #devdiscuss
  • jrgifford Mar 28 @ 9:40 PM EDT
    We have a project where our docs are a part of the process - PRs aren't supposed to get merged until docs are updated. #devdiscuss
    In reply to @twobree
  • ICBMRV Mar 28 @ 9:40 PM EDT
    during if posible. And read my code againg some time after finishing, but before asking anyone for code review #DevDiscuss
    In reply to @ThePracticalDev
  • gumnos Mar 28 @ 9:41 PM EDT
    And more often than not, *I* am the next guy using the lib. I try not to hate him. 😉 #devdiscuss
    In reply to @ckku_tommy, @ThePracticalDev
  • twobree Mar 28 @ 9:42 PM EDT
    We document during and after we code. What's more important is having a workflow with minimal friction so editing is easier #devdiscuss
  • billperegoy Mar 28 @ 9:43 PM EDT
    In an ideal world, part an agile sprint review/demo would include looking at docs. #devdiscuss
    In reply to @ThePracticalDev
  • twobree Mar 28 @ 9:43 PM EDT
    Creating a new commit for every tiny change in a README is annoying. Multiple people contributing to a wiki is easier for us. #devdiscuss
  • itsradditude Mar 28 @ 9:43 PM EDT
    If docs are the map, is readable code like a nice well-maintained road? #devdiscuss
    • KathyApplebaum Mar 28 @ 9:36 PM EDT
      Our code base is a couple million lines. No one dev knows it all -- docs are the roadmap that gets us to the readable code. #devdiscuss
      In reply to @ThePracticalDev
  • twobree Mar 28 @ 9:44 PM EDT
    Having 💩 documentation is better than nothing. So brain dump and fill in those gaps in a way that's easiest for YOU #devdiscuss
  • gumnos Mar 28 @ 9:44 PM EDT
    While I don't currently docker/vagrant, I'm a big fan of Live Documentation, living & changing with the source's intent #devdiscuss
    In reply to @levhita
  • billperegoy Mar 28 @ 9:45 PM EDT
    Actually out-of-date documentation is worse than none. It misleads those jumping into the project later #devdiscuss
    In reply to @twobree, @DevDiscussHQ
  • Nick_Divona Mar 28 @ 9:45 PM EDT
    in theory, during. In practice, after.. #devdiscuss
    In reply to @ThePracticalDev
  • mgasparel Mar 28 @ 9:46 PM EDT
    @ThePracticalDev How do you make sure docs and code/reality do not drift apart over time? #DevDiscuss
    In reply to @ThePracticalDev
  • ThePracticalDev Mar 28 @ 9:46 PM EDT
    Any sage advice for someone who knows what they probably *should* be doing, but has bad habits surrounding documentation? #DevDiscuss
  • sebnitu Mar 28 @ 9:47 PM EDT
    I write docs as I finish components/features. They're usually pulled from comments that I've been writing as I code. #devdiscuss
    • ThePracticalDev Mar 28 @ 9:20 PM EDT
      HOW do you document a project, where do the docs live, what guidelines/services/tools help you with your docs? #devdiscuss
  • MattHutchison43 Mar 28 @ 9:47 PM EDT
    some projects need it. SharePoint (yeah), esp. older versions and you'll never find all of the bits without em. #devdiscuss
    In reply to @ThePracticalDev
  • bendhalpern Mar 28 @ 9:48 PM EDT
    Please send help 🙏 #DevDiscuss
    • ThePracticalDev Mar 28 @ 9:46 PM EDT
      Any sage advice for someone who knows what they probably *should* be doing, but has bad habits surrounding documentation? #DevDiscuss
  • jessemonroy650 Mar 28 @ 9:48 PM EDT
    After the fact, could be a revision. #devdiscuss https://t.co/HdPdcfPWSg
    • twobree Mar 28 @ 9:42 PM EDT
      We document during and after we code. What's more important is having a workflow with minimal friction so editing is easier #devdiscuss
  • mrm8488 Mar 28 @ 9:48 PM EDT
    best tip. On writing docs think that it will be read by dumb guys. #DevDiscuss
    In reply to @ThePracticalDev
  • __biancat Mar 28 @ 9:48 PM EDT
    If you can't write separate documentation, at least do the docstrings in the code! Add a linter that will bug you to do them :) #DevDiscuss
    • ThePracticalDev Mar 28 @ 9:46 PM EDT
      Any sage advice for someone who knows what they probably *should* be doing, but has bad habits surrounding documentation? #DevDiscuss
  • sebnitu Mar 28 @ 9:50 PM EDT
    Don't wait till the project is finished to start writing the docs. It's a huge writing project if left last. #devdiscuss
    • ThePracticalDev Mar 28 @ 9:46 PM EDT
      Any sage advice for someone who knows what they probably *should* be doing, but has bad habits surrounding documentation? #DevDiscuss
  • jessemonroy650 Mar 28 @ 9:50 PM EDT
    @ThePracticalDev #devdiscuss https://t.co/gNEoplezhL https://t.co/04lKbxXW1a
    In reply to @ThePracticalDev
    • jessemonroy650 Mar 28 @ 9:43 PM EDT
      Docs after the fact are historical and/or a new version.
  • gumnos Mar 28 @ 9:50 PM EDT
    Dev-facing docs: during High-level stakeholder docs: before/during User docs: during/after #devdiscuss
    In reply to @ThePracticalDev
  • gumnos Mar 28 @ 9:51 PM EDT
    Docs written during, but edited after allow for a feedback cycle to improve UX. #devdiscuss
    In reply to @billperegoy, @ThePracticalDev
  • lucus_patrick Mar 28 @ 9:51 PM EDT
    make documentation (any - wiki/docs/docstrings/etc) a part of each task acceptance criteria #devdiscuss
    In reply to @ThePracticalDev
  • billperegoy Mar 28 @ 9:52 PM EDT
    Use the docs to teach others as you go. Writing as if you’re teaching makes for better docs. #devdiscuss
    In reply to @ThePracticalDev
  • MattHutchison43 Mar 28 @ 9:53 PM EDT
    Calendar event to update docs that I didn't do during development. Don't clear it until they're done. Popups get old. #devdiscuss
    • ThePracticalDev Mar 28 @ 9:46 PM EDT
      Any sage advice for someone who knows what they probably *should* be doing, but has bad habits surrounding documentation? #DevDiscuss
  • __biancat Mar 28 @ 9:54 PM EDT
    & for those that pride themselves on being good sw engineers: developing a good habit w/ docs (like comments) is part of that #DevDiscuss
    • ThePracticalDev Mar 28 @ 9:46 PM EDT
      Any sage advice for someone who knows what they probably *should* be doing, but has bad habits surrounding documentation? #DevDiscuss
  • twobree Mar 28 @ 9:54 PM EDT
    I haven't participated in #devdiscuss much lately, but I am tonight. I've found documentation to be so helpful, and I enjoy writing it.
  • gumnos Mar 28 @ 9:54 PM EDT
    Only if they don't evolve through the lifecycle of the code. Can make a nice starting point. #devdiscuss
    In reply to @billperegoy, @ThePracticalDev
  • jacmoe Mar 28 @ 9:54 PM EDT
    documentation is important bc it shortens the time it takes 2 pick up the train of thought that produced it. #devdiscuss
    In reply to @ThePracticalDev
  • mscccc Mar 28 @ 9:54 PM EDT
    Tests = majority of code documentation. Readme's/user facing docs written after or during. Ideally is auto generated. #devdiscuss
    • ThePracticalDev Mar 28 @ 9:36 PM EDT
      What is best, writing documentation before, during, or after writing code? And besides best practice, what do YOU do? #DevDiscuss
  • jayrav13 Mar 28 @ 9:54 PM EDT
    Not "sage", but see fellow devs as customers - deliver docs that work best for everyone to pick up where you left off! #devdiscuss
    • ThePracticalDev Mar 28 @ 9:46 PM EDT
      Any sage advice for someone who knows what they probably *should* be doing, but has bad habits surrounding documentation? #DevDiscuss
  • ICBMRV Mar 28 @ 9:56 PM EDT
    other good question is how often you document at all :) #DevDiscuss
    In reply to @ThePracticalDev
  • __biancat Mar 28 @ 9:57 PM EDT
    really this goes back to the (correct) notion that being a good sw engineer != being a good *coder*. #DevDiscuss
    In reply to @__biancat
  • twobree Mar 28 @ 9:57 PM EDT
    Depends on the bad habits I guess. Start with a blank slate. As you use a library, make a list of why you decided to use it. #devdiscuss
    • ThePracticalDev Mar 28 @ 9:46 PM EDT
      Any sage advice for someone who knows what they probably *should* be doing, but has bad habits surrounding documentation? #DevDiscuss
  • twobree Mar 28 @ 9:58 PM EDT
    From that list, you can eventually make a page for each lib with the why, and how to set it up. As well as gotchas you ran into #devdiscuss
  • __biancat Mar 28 @ 9:59 PM EDT
    w/ engineering, you need to make decisions that directly and heavily impact ur future selves, teams, reduce tech debt #DevDiscuss
    In reply to @__biancat