
Ask HN: What steps do you take to plan a new project? - foxfired
How do you plan&#x2F;document your project?<p>Every time I start one, it is a combination of code, research, prototyping, sparse documentation. In other words it is very disorganized. At some point I have a bunch of different files, apps, documents, not entirely related that I have to stitch together to make sense of anything.<p>Does any one have a solid process for planning a project?
======
christophilus
My process feels much less like engineering and more like utter chaos, but it
works for me.

I start by defining the minimum viable product. Emphasis on minimum. It should
be painfully minimal, and missing all sorts of features, but works roughly
well enough to be a good litmus test.

That's it. Then I build it.

Based on the feedback / information gleaned from building the MVP, I often
pivot. This frequently involves tossing some things out and rewriting other
things. But generally, it means planning the next phase. Here, I ask, "What is
the single most important thing I can do to make this project more useful for
the intended users?" And that's what I design / build.

Repeat indefinitely.

[Edit: Documentation is sparse. I like to comment the top of each source file
with a brief description of what it's for. If there's something really key to
the project or that is reused a lot, I'll drop a readme into the same folder
as the source, and document it the way I would an OSS library.

Regarding prototypes, it takes a lot of discipline, but I always throw 100% of
my prototypes away. In the past, I didn't do this, and I always regretted it.]

~~~
muzani
Oh that's interesting. I do the same thing but treat it as an engineering
process.

------
franciscop
Heavily refactor the code and files constantly. Split a huge file into
different files, put them into "src" or "app", etc. You should be doing this
fairly frequently if there was little planning or the project is quite
experimental.

When you have everything clear from the beginning try to anticipate and plan
the structure beforehand. But still refactor as needed.

As the final version is near, start improving/making the documentation. Too
early and you'll have to change many things, too late and it'll seem like a
huge different optional task (which it is normally not). BTW, I am the creator
of [https://documentation.agency/](https://documentation.agency/) if you need
some help there.

~~~
_eht
Documentation as a service sounds really valuable to me as an engineer. I
personally love solving a problem and building a solution framework, but never
feel I do enough justice to help whomever comes after me.

~~~
franciscop
The target is not so big as I initially though. Individual developers would (I
think) not normally pay for that, and mid-big companies have their own team.

So this is either for developers who can spare some money for great docs or
for small companies doing OSS.

Question, what is stopping you from contacting through the form? Maybe I can
also learn how to improve it.

------
indescions_2017
First design the team workflow. Github / Slack / Pivotal / CircleCI / etc. Are
enough to manage any distributed team. But make sure you hard encode the
practises as rules. Decide beforehand: are we doing weekly sprints or all-
hands release milestones? And make sure everyone is onboard and sticking to
the rules. This is useful even (or especially) as a solo developer. And could
just be as basic as a google doc spec. But design the process before beginning
the product. Of course you don't have to be extremely orthodox about it. The
process evolves with the project. But having that baseline of communication
channel flow and global source of truth is rather critical.

Then, you should be hearing the voice of Peter Norvig as he demonstrates a
Sudoku Solver in your head. "Solve the problem first". Make sure your tech
actually functions before building the UX, product or company around it.
Actually, in my experience, its only once you explore the problem space that
the use cases begin to pop out at you.

Another trick to jump start inspiration is to have something tangible. This
could be a brand name for which you register the domain. Or a unique logo.
This first baby step to make it "real" can often become a rallying point that
drives initial momentum.

------
mbrock
My first thought is "How much of this can I get to work in a day or two using
mostly shell scripts, existing programs, and text files?"

My first drafts of web apps always look exactly like this:

    
    
        <!doctype html>
        <title>Foo
        <link rel=stylesheet href=index.css>
        <div id=app />
        <script src=index.js></script>
    

I've also embraced a kind of chaotic method, analogous to "write drunk, edit
sober."

Getting something to work with purposefully bad code is a productivity hack
for me. Refactoring it later is enjoyable and often necessary, but the
separation of mindsets is crucial.

It's like what the XP guys called spike solutions. Make sure that you can
plausibly get from A to B without caring at first about performance and
elegance. This gives you information and confidence.

In my experience, developing cannot be a clean and controlled process unless
you're doing something you've already done before.

------
muzani
Company project? Google's design sprint is good methodology.

Personal project?

1\. Market research. If it's something worth doing, someone else has done a
similar solution. Ideally, the competitor is a hacky solution, built off some
forum, community, or an Excel sheet, and has become really tedious. If there
is no competitor, there is no market.

2\. Pull feature lists out of their feedback of that tool. A couple of hours
reading reviews and Reddit discussions does a better job than focus groups.

3\. Hack a disposable prototype. Key word disposable. It will be buggy and
ugly but do a better job than the existing tool. The key is to gather
information.

4\. Get feedback from the prototype. Ideally do this in person - you want to
see the point where people get excited.

5\. Focus on the features people love. Think about suggestions and complaints.
Don't implement immediately, but find out why they ask for it.

6\. Iterate and improve.

~~~
justboxing
> If there is no competitor, there is no market.

Wut. If Steve Jobs had thought that or followed this advice, there would be no
iPhone.

~~~
jononor
Many million mobile phones were being sold per year, from 10ish big companies.

~~~
codegladiator
Would you like to owe one of those phone or the iphone 1 now ?

~~~
muzani
I did own one of those Symbian phones for a long time and only switched to a
Samsung S2 later on. The iPhone 1 had worse games and was too expensive for
the regular things like calls, SMS, music, and photos.

------
tmaly
I try to keep a fairly small number of sub folders that are well named. I keep
a file that lists what each folder is for. I also like to keep a TODO.txt that
I append to the top with a date an what needs to be done next.

I write a few tests and some good comments on code that I feel is likely to
change. There is always the tendency to not write either of these, but I think
it is important if you want to iterate fast.

------
graycat
For my present project, where I'm trying to build the first company worth $1
T:

At my computer I noticed that I didn't have a good way to do something I
wanted to do.

Hmm, could there be a project here? Well, I noticed that likely and apparently
so far there wasn't a good way to do that and that nearly every user of the
Internet in the world might want to use a good solution 1-5 times a week.

So, thought of how I might get a solution:

So, okay, broadly implement the solution as just a Web site.

Next, at the site and elsewhere, collect some good data, use some good,
original applied math derivations, and report the results that people would
like for the problem.

I investigated what had been done so far, didn't like any of it, and guessed
that I might be able to do better.

So, I put my feet up, popped open a cold can of diet soda, reviewed some of my
favorite grad school pure math material, took some fairly standard themes in
pure and applied math, and did some fast derivations. There I needed to solve
some problems from not always having as much data as I would like and some
problems in making the data manipulations and calculations nicely fast.

Really, there were those two problems and at least two more. I found what
appeared to be good enough math approximation solutions to all four of the
problems.

I turned the work, the problem description, the broad ideas for getting the
data, the math ideas, etc. into a paper I typed into D. Knuth's math word
wacker TeX. There I also typed in the math derivations with the assumptions,
definitions, theorems, and proofs.

I reviewed, thought about, and gave a critical review of the material and
concluded it looked solid enough.

The math derivations were a solid outline of the crucial core of the software.
I also did some work on the design of my SQL database tables, again to make
the data handling easy and fast. Then the rest was mostly just for the Web
site. So, I learned some HTTP, HTML, CSS, and Windows ASP.NET, designed the
Web site and its Web pages, and did the programming for the Web pages. The
applied math code is in other programs that communicate with the Web software
via object instance de/serialization from/to byte strings and sent via just
TCP/IP sockets. That applied math software is single threaded, and the queuing
is handled by the TCP/IP FIFO queuing.

There were two big, unexpected problems:

(A) Documentation for what I was using on Windows. So for .NET, SQL server,
etc., I found, downloaded, read, abstracted, and indexed 6000+ Web documents.
That took a long time.

(B) The motherboard of my development desktop computer got temperature
sensitive and gave me some serious boot partition data corruption.

From the beginning through the TeX document, the work went so fast there
wasn't much concern about planning.

Once the programming started, the work that was unique to my project was fast,
fun, and easy, but unexpected problems (A) and (B) were very costly.

"Fast, fun, and easy"? Yup, since I did the original applied math, programming
that was easy for me. For learning HTML, CSS, SQL, etc., that was plenty easy
enough.

But a typical problem was a seemingly trivial one -- getting a connection
string my Web page code could use to get to SQL Server. Just getting a
connection string to work took about a week of throwing stuff against the wall
to see if it would stick. I did find a connection string that worked; I still
have no idea why that connection string does work but the dozens of others I
tried didn't.

At this point the plans are:

(1) Get the development computer back to working again; the main work here is
a lot more software installing and configuring.

(2) For some of the crucial applied math code, some of the data indexing is a
bit tricky. I've tested that code three times finding no problems, but I want
to test it once more.

(3) Then I want to complete a good alpha test.

(4) I'll need to gather and add quite a lot of initial data to my SQL Server
data base.

(5) I'll do a semi-public beta test; I intend to ask for beta testers on HN.

(6) Then I'll do the routine things to go live, e.g., tax ID, telling my
county about my business,getting a business bank account, etc.

(7) I'll see what the ad networks want me to do to run their ads.

(8) I'll make some efforts at publicity.

(9) I'l go live.

All of (1)-(9) are routine and shouldn't take too long.

Net, the stuff unique to my project was so easy (with my background) that no
planning was necessary. For the rest, it was all routine except for unexpected
things that I could not have planned for.

But, as software development goes, it's not a really big project: The
production code is 24,000 programming language statements in 100,000 lines of
typing -- lots of comments in the code. So, with such a small software
project, the unexpected problems shouldn't be to serious.

So, the code is short and efficient but, due to the math, should provide the
first good, and an excellent, solution to the problem.

So, really, I did do some planning, but due to the unexpected problems the
planning didn't do much good!

Maybe the usual lesson is that planning can work well if doing a project one
more time where have successfully done a dozen or so earlier versions!

That also holds just for cooking beef stew: The first effort might take too
long and yield stew that's not very good! But trial 12 might be fast with
terrific results!

~~~
pjmorris
> So, really, I did do some planning, but due to the unexpected problems the
> planning didn't do much good!

'Plans are useless, but planning is indispensable.' \- Dwight David
Eisenhower, who knew a bit about planning.

