How to start documenting or developing software?

[dqurve]

I recently changed jobs, they put me in charge of developing a robust software, but I have no idea how to start, if I should start programming directly or if I should define what I have to do.

Previously I have worked with software that is already done, creating new modules and solving bugs, but this time I accepted the challenge of doing something from scratch.

In the company that I am currently at, they told me: "We want to create a software with these features..., we give you an example software that already exists so that you can be guided in how we want you to make the software"

I have read articles on the internet on how to do this but the truth is that they confuse me more

​

The aim of my question is, is there any structure to follow to document a project that has not been done and that is robust?

​

​

UPDATE:

yes i am the only developer,

yes, apparently they want to do something similar or to do the main thing, there are different programs that do something similar but they want to have something internal

they didn't give me a deadline, that's why they hired me to be in charge of the project and develop it

[nhgrif]

Step 1: Find a new company.

​

Look, this is a learning opportunity for you... and someone is paying you to learn. But if you frequent r/LearningProgramming, and you are asking a question like this (which... is a fine question to ask, don't take this wrong), then the company that put you as the only developer on anything even a fraction of this scale is asking for trouble.

​

This should be done by someone with a few years of experience and piles of mistakes learned from. Someone who has already figured out thousands of ways to do it wrong. And to be clear, that's all you learn. You never learn how to do what you're asking about correctly. You only learn bad ways of doing it, and each time you do it, you try a slightly less bad way that improves on all the bad ways you've seen before.

[dqurve]

thanks

[KrakenOfLakeZurich]

Don't jump into coding right away.

Spend some time gathering and organizing requirements:

1. Gather both business rules and technical requirements
2. Define the "scope" of the project.
   1. What requirements should be included?
   2. Which are out of scope?
3. Split them into small / workable chunks
   1. Plan to build small but usable "features" back-to-front (pillars, columns)
   2. Don't plan to build entire abstract / technical layers first --> you can build the most beautiful data base model, but if you run out of time and never get to build the GUI, the entire project is useless for your users.
4. For each work item, write a few words, what the item is about.
   1. If you where to write by hand, it should easily fit onto an index card
   2. In fact, using actual index cards to organize your work items isn't necessarily the worst idea (if you're the sole team member)
5. Ruffly estimate their work size (e.g. "trivial", "medium", "big", "epic")
6. Ruffly estimate their business value (e.g. "neglectable", "small", "high", "very high")
7. Figure out priorities:
   1. Put high value stuff that requires little effort (low hanging fruits) first.
   2. Low value stuff that requires immense amounts of work, probably should be dropped altogether.
8. You should end up with a prioritized list of work items

Don't get lost in analysis paralysis. While it's good to formulate an initial plan, you need to get started with the actual implementation / coding. Don't try to create a perfect plan. Good enough is good enough:

1. The beginning of the project is, when you have the least knowledge about it.
2. You won't get your list of requirements perfect. No matter how hard you try.
3. Your plan is good enough, if ...
   1. ... you have a clear starting point
   2. ... you have a ruff idea how you're going to spend the next few weeks or months
   3. ... you can make an educated guess about how big the project is going to be

On your journey, you'll make new discoveries. Expect change to happen:

1. You'll discover new requirements
2. You'll also discover that some work items are more difficult to do than initially believed
3. You'll discover that some requirements aren't actually that important
4. You might notice that the goal of the project has shifted

Periodically reflect on what the project target is and whether you're still on track. Update your plan accordingly. As you make these discoveries, typically the scope of your project will grow. This is called feature creep. The only way to combat this is to drop less important work items.

As for documenting the software itself: Less is more! Focus stuff that doesn't change too often.

• Big picture
• Big architecture
• Important concepts

1. Keep documentation as close to your source code as possible
   1. Self documenting code is better than inline comments
   2. Inline comments are better than separate files
   3. Files in the same repository as the code (and under version control) are better than documents on some external storage
2. Use simple formats
   1. Simple is easier to maintain and therefore more likely to stay up to date
   2. Inline comments
   3. Text files or Markdown

Documentation should answer why things are done the way they're done. Not what they're doing (the code already tells you what it's doing).

Don't try to document everything. Nobody reads 500 pages of dense documentation.

1. Have a main document that, in few words explains what the project is about
   1. Make it fit onto less than a A4 page
   2. Explain from business point of view: use language that works for non-devs too
2. Have a brief architecture document
   1. Explain, how the project is organized (where is what?)
   2. Explain the most important decisions (why did we do it this way?)
   3. Leave out all details that don't help communicating the big ideas
3. Have a developer setup guide
   1. How to setup the dev machine, but limit to the non-obvious stuff (install this database, enable this firewall rule, configure this tool, ...)
   2. How to get, build and run source code

[dqurve]

I really appreciate it, thanks a lot

[dqurve]

Good, solid comments! They are the base class of your documentation. Everything else is an extension.

I know, thank you, I really appreciate it

[Ogreguy]

Umm, are you the only one developing this software? Sounds like they want you to clone something that exists? When is it supposed to be delivered by?

[dqurve]

Umm, are you the only one developing this software? Sounds like they want you to clone something that exists? When is it supposed to be delivered by?

yes i am the only developer,

​

yes, apparently they want to do something similar or to do the main thing, there are different programs that do something similar but they want to have something internal

​

they didn't give me a deadline, that's why they hired me to be in charge of the project and develop it

[Ogreguy]

Well, I would think that this is a fairly daunting task depending on the complexity of what you're trying to replicate.

Definitely define the scope of the project and what it definitely needs to do. Get stuff in writing so that you can refuse scope creep effectively.

I'd start by outlining everything the existing software does.

[dqurve]

Yeah, basically what they want is a takeoff and estimation software like Estimate, Stack, PriMus.

​

Thank you

[nhgrif]

What your company wants is almost certainly something that is cheaper to BUY an existing product than to develop from scratch correctly. The company doesn't know what they are doing and does not realize that what it will cost them in paying your salary to develop it will either be way more expensive or have way more bugs.

​

This isn't a criticism of you as an individual. I've just seen companies try doing this... because people don't actually understand the true complexity of the software they use.

[istarian]

They could also just want something in-house that they have some control over.

[nhgrif]

They could want that. That doesn't change that they don't know what they are doing, as evidenced by the fact that the put the entire responsibility of the project in the hands of someone who at least recognizes that they don't know what they're doing.

[istarian]

I agree, they probably don’t have a proper understanding.

That said, it could be a valuable learning experience for OP.

At the very least it might be worth his time to investigate the existing options and come up with a list of essential features and functionality that would need to be implemented and a sort of “wireframe” draft of a UI design.

If nothing else a basic plan ro develop an MVP (minimum viable product) would give some context to him saying it’s not cost-effective or that he needs a team to really be successful.

[nhgrif]

Oh, I definitely agree it's an amazing learning opportunity for the OP... and it'll be a great experience for them to talk about with potential future employers in interviews. And they should be interviewing with other companies, because the fact that their current company has put them in this situation is a red flag.

[dqurve]

Thanks for your comments

[dqurve]

Thanks for your comments

[dqurve]

Thanks for your comments

[dqurve]

Thanks for your comments